News for hackers. Stuff that matters.
Re:Writing system software: code comments by chrisweekly on Sunday October 07, 2018 @01:36PM (#18161697)
IME (20 years in web-related software dev / arch / mgmt), the best ROI in this area comes from two things:

- good commit messages

- references to persistent requirements artifacts (eg Trello cards, Jira tickets, whatever)

YMMV... but really doing these two things makes a huge difference.

Re:Writing system software: code comments by thaumaturgy on Sunday October 07, 2018 @01:43PM (#18161739)
Both of your examples require the developer to access some resource outside of the code itself in order to understand what the code is doing (or why it is doing it).

So those things are both good also, but I consider them to be a fallback for cases where the code isn't commented like it should be.

Re:Writing system software: code comments by chrisweekly on Monday October 08, 2018 @10:49AM (#18167957)
Comments can provide context by simply providing a link like "See Issue/ticket/card ID #123". That plus git blame, good commit messages, and feature branches named for the same ID, makes for a coherent whole -- without adding much overhead in terms of comment writing and maintenance.