I try to use very descriptive but short variable/function names, and I use those names over and over again in different projects so I know exactly what that variable does or what that function is etc...
This. Whenever I use placeholder variable names (like "aux" "temp" or single letter variables) I, invariably
, get into trouble later.
Comments are very important too, but they need to be well structured or else they add to the confusion.
I've taken to using the javadoc comments at the start of a method/class, including a concise description of what is going on (with all parameters documented) rather than inlining comments all throughout the code (some inlining is still used, but it isn't the bulk of the comments now).
Another technique is to properly encapsulate functionality. Having a single function do everything is a mess, splitting into smaller chunks can make it more readable and sometimes *gasp* even reusable
In any case, in my opinion/experience any complex project you will have to re-learn when you get back to it after a while, so writing it like you would write documentation for someone else to take over will minimize the re-learning period, and also be great training if someday you expect to work as part of a team.
My pet peeves:
- Use some decent Logging solution, log lines also serve as documentation.
- Do NOT just capture generic Exceptions when you can predict what specific exceptions will be thrown. And if you do, LOG THE TYPE.
- Magic Numbers* are the silent enemy, exterminate them with extreme prejudice.
Whenever a value (not necessarily a number) is hard-coded somewhere in code. I obsessively turn said values into properly defined constants, which means I won't forget what the number/value means, and I can easily search the value when needed.
public double pmtr(double r)
return 2.0d * 3.1416d * (r * r);
Not So Bad Example:
Kill It With FIRE Example:
public static final double PI = 3.1416d;
public double Perimeter(double Radius)
return 2.0d * PI * (Radius * Radius);
public double f_a_p(double var)
return 6.2832d * r;