Some time ago, I stumbled upon ApexDoc, which brings the idea of Doc Blocks from JavaDoc to Apex...kinda. Since then, I've been making a conscious attempt to document more of my code using this format. Being the only full-time dev at my company is making that difficult at times (though perhaps I've found a good goal for my next performance review).
For the benefit of those unaware of Doc Blocks, it's simply a multi-line comment that has annotations such as @description
which give a specific piece of information about that thing that you're documenting.
From my admittedly limited knowledge, this seems to have emerged as the de facto documentation standard over the years for the languages that I've used the most (C++, Java, JavaScript, and PHP).
/**
* @description Base class used for creating widgets
*/
public class Foo {
/**
* @description Type: String
* Defaults to 'Baz'
*/
public String bar = 'Baz';
/**
* @description Basic getter. Memo-izes the return result of someClass.something() if bar is null.
* @return A String with special instructions
*/
public String getBar(){
if(bar == null){
bar = someClass.something();
}
return bar;
}
}
ApexDoc is a CLI, Java-based tool that can scan Apex class files for docblocks, and generates static HTML pages from them. I haven't actually run the tool myself, but think of it generating something like the Apex developer docs that Salesforce provides today. I imagine it wouldn't be hard to add as a step in an existing build process with a CI tool like Jenkins.
Even if you don't use the tool to generate the documentation in HTML format, simply using a docblock to give an executive summary of your class/method/whathaveyou should help other devs digest your code.
Beyond that, my only other documentation strategy is to add comments above snippets of code that I've spent a good deal of time on adjusting (for a bugfix, getting a failing test to pass, optimizing, etc...). If not for anyone else, then for me so I can remember (months later) why the hell I needed to structure the code the way I did.
As an example, here's a comment I made above a while loop that is used in a method to add a number of business days to a given date
// The number of business days we add by adding/subtracting x days from tempStartDate/tempEndDate
// will always be less than or equal to x.
// Thus, we can always add/subtract a number of days equal to target - actual, and never overshoot.
// Simply lather, rinse, repeat until we arrive at our target.
while(numBusinessDays != targetBusinessDays){
workingDate = workingDate.addDays(targetBusinessDays - numBusinessDays);
numBusinessDays = this.businessDaysBetween(startDate, workingDate);
}