Re:Writing system software: code comments
by keithnz on Sunday October 07, 2018 @04:16AM
(#18159443)
Really nice article. While I'd quibble about some of the details, this categorization of comments is really good. Really good discussion around each category too.
Not sure if is a separate category or not, but I often do Quirks type comments especially when dealing with APIs of libraries with links to relevant documentation ( even if though those links may go dead at some point, I'll capture the essence of the quirk in the comment and leave the link )
Re:Writing system software: code comments
by mkingston on Sunday October 07, 2018 @05:36AM
(#18159705)
Get a browser plugin to single-click archive the documentation with archive.org, then include that link in your comments. Yes, I do exactly this, I'm not just sniping!
Not sure if is a separate category or not, but I often do Quirks type comments especially when dealing with APIs of libraries with links to relevant documentation ( even if though those links may go dead at some point, I'll capture the essence of the quirk in the comment and leave the link )