[Dlang-internal] DMD Technical Debt

[Walter Bright]

DMD Technical Debt

As what happens with all long term projects, code accumulates cruft and technical
debt. People often ask what to do to improve things, so here's a list:

1. Adding attributes const/nothrow/pure/scope/@safe/private/etc.

2. Adding correct Ddoc function comment blocks. Do not use Ddoc comments for
overrides unless the overriding function does something different (as far as
the caller is concerned) than the overridden function. Ddoc comment blocks
are often overkill for nested functions and function literals; use ordinary
comments for those.

3. Get rid of strlen/strcmp and using D arrays instead.

4. Use `ref` instead of raw pointers.

5. Use nested functions to get rid of rats' nests of goto's.

6. Look for duplicative code and factor out into functions.

7. Declare local variables as `const` as much as possible.

8. Use Single Assignment for local variables:

     T t = x;
     ...
     t = y;
     ...

    becomes:

     T tx = x;
     ...
     T ty = y;
     ...

9. "Shrinkwrap" the scope of local variables as tightly as possible
around their uses.

10. Similar to (8), use distinct variable names for non-overlapping uses.

11. Avoid use of mutable globals as much as practical. Consider passing them
in as parameters.

12. Avoid use of default parameters. Spell them out.

13. Minimize use of overloading.

14. Avoid clever code. Anybody can write clever code. It takes genius to write 
simple code.

15. Try to reduce cyclomatic complexity, i.e. think about how to make the code work
without control flow statements.

16. Try not to mix functions that "answer a question" with functions that 
"mutate the data".
I was able to successfully do this in escape.d, it wasn't easy, but it was well 
worth it.

17. Try to eliminate reliance on `global.errors`.

18. For aggregates that expose public access to fields, think hard about why this is
necessary and if it can be done better. Merely replacing them with read/write 
properties
accomplishes nothing. The more of its internal details can be made private, the 
better.

19. Try to use function prefixes:

'is' is the parameter in a certain category?
'has' does the parameter have a certain feature?
'can' for can I do X with the parameter?

Such functions should not be mutating the data nor issuing error messages.

20. The function return value variable should be named `result`.

21. The more constrained the scope of a name is, the shorter it should be.



NOT On The Table:

1. Grand renamings of variables and functions

2. Shuffling all the code about

3. Creating packages

4. As a general rule, any improvement that is implemented by using sed scripts
across the source tree is likely to be disruptive and unlikely to provide
significant improvement.

5. Changes of more than 500 lines need buyoff from Andrei or myself.

6. Reformatting.



Keep in mind that nearly all of this technical debt is MY fault.

As always, treating the above as sacred writ is a huge mistake. Use
your best judgement on a case-by-case basis. Blindly doing things just
adds more technical debt.