TODO - this
Document All The Things!*
*Don’t - read on and see first.
I’m big fan of documentation — whether it’s well-detailed README in a public GitHub project, coding standards for a development team or documentation blocks within code — I always find comprehensive notes or instructions invaluable when working on a project, whether legacy or brand new.
I’m going to focus on the last type in this blog - inline code documentation, or Doc Blocks.
Who’s this “Todo” guy, and why doesn’t he ever finish his code?— Callum Ashton
/** * @file grid - uses Masonry Layout NPM package to add functionality to the page grid. Needs shim for IE (even IE 11!). * @see [email protected] https://www.npmjs.com/package/masonry-layout} * @see [email protected] https://github.com/lazd/scopedQuerySelectorShim} * @author N. Redacted <[email protected]> */
You can even let people know that there’s something that needs refactoring:
* @todo Move into utils module
- Increases readability of code
- Lessens the cognitive load of figuring out what code does
- Can generate documentation in HTML format or reports from doc blocks
- Can clearly see ownership of code and get contact details
- “Code should document itself”
- Time it takes to write doc block comments
- Could just use Git logs to see who wrote a piece of code
- Updating and maintaining comments takes up time
- People don’t trust comments that are outdated