[quote=“opiop65,post:9,topic:47385”]
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.
*Magic Numbers: 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.
Bad Example:
public double pmtr(double r)
{
return 2.0d * 3.1416d * (r * r);
}
Not So Bad Example:
/** Easy as PI */
public static final double PI = 3.1416d;
/**Method Documentation: The formula is "2 * PI * RADIUS^2"
*@param Radius A parameter being documented
*@returns Return value also being documented */
public double Perimeter(double Radius)
{
return 2.0d * PI * (Radius * Radius);
}
Kill It With FIRE Example:
public double f_a_p(double var)
{
r*=r;
return 6.2832d * r;
}
