|
|
|
|
|
|
by trane_project
99 days ago
|
|
|
I think full literate programming is overkill but I've been doing a lighter version of this: - Module level comments with explanations of the purpose of the module and how it fits into the whole codebase. - Document all methods, constants, and variables, public and private. A single terse sentence is enough, no need to go crazy. - Document each block of code. Again, a single sentence is enough. The goal is to be able to know what that block does in plain English without having to "read" code. Reading code is a misnomer because it is a different ability from reading human language. Example from one of my open-source projects: https://github.com/trane-project/trane/blob/master/src/sched... |
|
|