Code can communicate “what” it does. But only comments can communicate “why” it does it! “why” is a broader truth that simply cannot be expressed in code. It involves requirements, feelings, experience
Good design (and thus documentation) rules to reach conciseness are these:
Don’t let methods with more than 3 arguments leak into your public API.
Don’t let methods / types with more than 3 words in their names leak into your public API.
Best avoid the above. If you cannot avoid such methods, keep things private. These methods are not reusable and thus not worth documenting in an API.
Keep things simple and concise
Create good documentation:
by keeping documentation simple and concise.
by keeping documentation close to the code and close to the API, which are the ultimate truths of your application.
by keeping your documentation DRY.
by making documentation available to others, through a ticketing system,version control, semantic versioning.
by referencing ticket IDs throughout your available media.
by forgetting about “external” documentation, as long as you can.
software that has thought-to-be-dead code that no one dares remove or code that desperately needs refactoring but involves too much risk to be refactored.
many software projects seem to go through the Jenga game lifecycle. Changes are easy at first in both cases but become increasingly difficult and risky as the game or project goes on and the structure (Jenga tower or project code base) becomes unwieldy.
Concurrent or Not: Nine Women Making a Baby in One Month
Ignoring Warnings: Sweeping Dirt Under the Rug or Hiding Junk in the Closet
Comments are Deodorant for Stinky Code
some comments have value (such as Javadoc methods describing pre-conditions and post-conditions and other contract details), but in-method comments often do seem to be extraneous or redundant at best, downright misleading or out-of-date in other cases, or must exist because the code they describe is inscrutable without them
Posted from Diigo. The rest of my favorite links are here.