[thisisit]

Early in my career I worked on legacy i-Series systems. One of things we were taught was to never write a code without putting in comments in the header. And the commends need to specify dates, ticket number for tracking, and the rationale behind the change. Every changed line had to be inside a block with the same ticket number, making it easier to simply Ctrl+F through the code.

Now I work on newer software and I frequently see people making changes without spelling out the rationale, dates, author etc. And it makes it harder to track what has happened and what does the code do exactly. When I tell people to comment it correctly they often reply about - how much time saving can be had by writing a clean code.

[fwip]

Nowadays we keep that information in the VCS. git blame gives you more reliable info than careful comments (assuming that the rationale is recorded in the commit message).

[lostcolony]

Integrate with a ticketing system, force commits to match a pattern, and you can ensure the rationale is tied to your ticketing system (i.e., commits/merges have to be prefaced with FOO-####)

[klardotsh]

This is generally great (and I do it on projects I'm confident won't be moving any time in their useful life), but if you ever switch VCS/ticket systems, it gets messy quick.

Ever moved from Github Issues to Jira/Trello or vice-versa? How about Bitbucket to Github (as I did for my current company)? That's a whole lot of context potentially being lost, either in tickets or PR discussions.

How much of that lost context would have ever been used anyway is up for debate, of course. In my experience the answer tends to be "rarely, but sometimes".

[sedachv]

This is why I discourage Free Software projects from using hosted issue trackers entirely, especially ones that are proprietary (such as GitHub). Mailing lists are the best solution for longevity and meaningful discussion. If you really need to, you can organize things in a file that is in the repository alongside the source code (Org mode is great for this), which has many significant advantages (and downsides, like not being point-click for PMs, but if your Free Software project has PMs, you have bigger problems that software cannot solve).

[james_s_tayler]

Often that sometimes is a life saver though...

[pcnix]

This happens on github/gitlab too, with pretty much all open source projects. It's definitely a cause for concern eventually, because the context for the problem and the rationale for decisions is now something that you have to maintain apart from just maintaining the codebase. Right now github etc do a good job of managing that for you, but the long term handling of this context definitely has scope to improve.

[maxxxxx]

Obviously this system will be obsolete in a few years too and nobody will know how to find stuff int it :-)

[james_s_tayler]

Well you know my last job I worked on a system that was a lot of 4gl under the hood and a Java application that sat on top calling the legacy 4gl code. The 4gl code had comments in the header with dates and ticket numbers. The dates stated late 80s and 90s. The ticket system was from 4 ticket systems ago so that was useless. The comments had become wrong over a period of 30 years of changes. The rationale for something in 1989 made a lot less sense for 2015. The author was now the boss for the whole office and hadn't touched code in 25 years so I can't go ask him about this function he wrote in 1989.

Entropy. It's not our friend. It's why we can't have nice things. Code bases suffer from bit-rot over time.

[FiddlyPack]

I think all of things you mention have value, but all of that information is (and in my setup, displayed inline) located in git. We keep ticketing, author, rational, and version changes, and you can walk through the changes with the tracked intentionality by stepping back through the version control.

[southern_cross]

I followed a similar protocol, but then I ran into a situation where good discipline kind of went out the window during "the great outsourcing". So when recently updated code had problems, because my info was the last actually properly recorded in the source code (even though I hadn't touched that code in years), someone might come gunning for me to fix the problems with "my" code. Not fun, especially when I might actually take a look at that code and see how badly the outsourced folks had mangled it!