4 ms·

I noticed a lot of suggestions in this thread assume you want to capture the institutional knowledge related to coding and software: - comments in the source c

I noticed a lot of suggestions in this thread assume you want to capture the institutional knowledge related to coding and software: - comments in the source code - commit messages - readme - code review - pair programming - variable naming and refactoring Which is all great, but at the same time narrow. What if I want to capture institutional knowledge when it comes to accounting, HR, PR, management, negotiations, suppliers, local laws, seasonal patterns etc. Perhaps there's a more abstract, generalized advice that could be applied outside of the realm of coding.

JohnBooty 7y ago
comments in the source code This is an unpopular opinion, but I fervently agree with it. It one of the most powerful ways to keep a codebase comprehendible. Some folks say, "That's what commit messages are for." Bullshit. When people say that, I suspect they've never worked on anything other than prototypes or toy projects. Good commit messages are a must, but they don't scale well when it comes to long-lived projects. Think of a source file that's had many dozens or hundreds of commits and refactorings. Tracking down the original author's intent can be very difficult - especially when the original commit doesn't reference what's happening on line 78 or whatever. Especially when there are dozens of such oddities in a single file. Some other folks also say, "Good code is self-describing." Again, bullshit. Maybe if you're writing code in a vacuum. But code gets weird and messy where it interacts with other things that are outside your control. I can read your code and see what it's doing. But your code cannot tell me the "why." The kludges you implement to work around bugs in other libraries/browsers/APIs are NOT comprehensible without some contextual information about the bug you're trying to solve. Ditto for all the weird business logic that creeps into applications. Why aren't we charging sales tax on Topeka on Tuesdays? Tax law? Were we running some special promotion? Did our vendor in Topeka already collect sales tax in some other part of the process? A quick comment can save the next maintainer hours of wondering. So, my rules are.... 1. Stick a comment in there if you are implementing a kludge/workaround based on some external thing. Wrote your own CSV parser because the one in the standard library is broken? OK, tell me that so that I know this was a conscious choice and not a matter of you simply not knowing that the standard library existed. 2. Stick a quick comment in there if you are implementing business logic. Even if your comment is simply "Implement Bob's marketing idea for the job fair" that would at least give me something to go on five years from now when I'm wondering if I can delete that bit of code. 3. No need to document basic stuff. Retrieving some records from the DB? Writing to a file? No problem. Assume the person reading your code is a competent programmer. No need to describe that stuff.
- zmj 7y ago
  > Some folks say, "That's what commit messages are for." Bullshit. When people say that, I suspect they've never worked on anything other than prototypes or toy projects. Good commit messages are a must, but they don't scale well when it comes to long-lived projects. Yep. I've seen codebases that have migrated source control and issue trackers multiple times - sometimes migrating history, sometimes not. The only ancient knowledge that has survived is the code comments.

JohnBooty 7y ago

comments in the source code This is an unpopular opinion, but I fervently agree with it. It one of the most powerful ways to keep a codebase comprehendible. Some folks say, "That's what commit messages are for." Bullshit. When people say that, I suspect they've never worked on anything other than prototypes or toy projects. Good commit messages are a must, but they don't scale well when it comes to long-lived projects. Think of a source file that's had many dozens or hundreds of commits and refactorings. Tracking down the original author's intent can be very difficult - especially when the original commit doesn't reference what's happening on line 78 or whatever. Especially when there are dozens of such oddities in a single file. Some other folks also say, "Good code is self-describing." Again, bullshit. Maybe if you're writing code in a vacuum. But code gets weird and messy where it interacts with other things that are outside your control. I can read your code and see what it's doing. But your code cannot tell me the "why." The kludges you implement to work around bugs in other libraries/browsers/APIs are NOT comprehensible without some contextual information about the bug you're trying to solve. Ditto for all the weird business logic that creeps into applications. Why aren't we charging sales tax on Topeka on Tuesdays? Tax law? Were we running some special promotion? Did our vendor in Topeka already collect sales tax in some other part of the process? A quick comment can save the next maintainer hours of wondering. So, my rules are.... 1. Stick a comment in there if you are implementing a kludge/workaround based on some external thing. Wrote your own CSV parser because the one in the standard library is broken? OK, tell me that so that I know this was a conscious choice and not a matter of you simply not knowing that the standard library existed. 2. Stick a quick comment in there if you are implementing business logic. Even if your comment is simply "Implement Bob's marketing idea for the job fair" that would at least give me something to go on five years from now when I'm wondering if I can delete that bit of code. 3. No need to document basic stuff. Retrieving some records from the DB? Writing to a file? No problem. Assume the person reading your code is a competent programmer. No need to describe that stuff.

zmj 7y ago
> Some folks say, "That's what commit messages are for." Bullshit. When people say that, I suspect they've never worked on anything other than prototypes or toy projects. Good commit messages are a must, but they don't scale well when it comes to long-lived projects. Yep. I've seen codebases that have migrated source control and issue trackers multiple times - sometimes migrating history, sometimes not. The only ancient knowledge that has survived is the code comments.