3 ms·

You should document what the code should do, why it exists, and why you did it a certain way. In my current role, I've inherited a decade of cobbled together s

by js2 4y ago

You should document what the code should do, why it exists, and why you did it a certain way. In my current role, I've inherited a decade of cobbled together shell, python, ruby, javascript, java, and groovy that together constitute a large part of our build release system, spread across a dozen or more repos, written by over a dozen developers. This code is undocumented, untested, brittle, and riddled with heisenbugs. Among other things was a developer who was terrified of ever breaking anything. So whenever he needed to make a change, he'd duplicate the code. One recent example I dealt with is three copies of a script: copyReports.sh, copyReports-alt.sh and copyReports-multi.sh. In addition are symlinks to each script without the .sh extension. Before I could even touch this code I first had to instrument it to record when it was run, to figure out which of these was even in use, and under what circumstances. I had to try to tease out why the developer made the extra copies, because he didn't document the reason when he did so. I had to guess why there were both version with the '.sh' extension and why not. The developer hadn't written so much as a single sentence explaining his thinking at the time. So no, I don't expect you to document your bugs, but maybe in the process of writing a commit message, or a test, or some documentation, you may realize on the second thought that you made an error in the code and save yourself from a bug. But in any case, at least when you come across your bug a year from now, it'll be clearer what the code was supposed to do because you wrote it down at the time, as opposed to what it actually did. WesolyKubeczek, can I ask how long you've been a developer and what size projects you've worked on? I've been writing code professionally for over 20 years, worked at companies and on projects big and small, and have used revision control systems since RCS/SCCS, on through clearcase and subversion, mercurial and git. I've worked with code old and new. In my experience, documenting things along the way is invaluable to building a sustainable code base. You may think that shipping and velocity is all that matters and that writing a commit message is nothing but friction. But that hasn't been my experience, neither at startups nor at fortune 500s. Code that's going to be around more than 6 months is going to be revisited. To add features. To fix bugs. Even just to delete it. And when that time comes, having a commit message saves time, much more time than was spent writing the message in the first place. I personally consider it development malpractice not to document my code along the way.

WesolyKubeczek 4y ago
> WesolyKubeczek, can I ask how long you've been a developer and what size projects you've worked on? Just over some 20 years. Haven't used RCS, but had some CVS and this version control system you have when you put file1.php, file2.php, file3.php, etc onto the production FTP, update includes, and hope you have caught all includes. Wasn't my idea, so don't ask. Codebases starting at several hundred thousand lines of code and up, mostly old ones. What I have learned is that given enough time, everything is a lie. Documentation is a lie probably as soon as you're writing it. Comments in the code are lies in a month. Commit messages are lies too, by the time you bisect some sonofabitch of a bug, the offending commit will point at something unrelated entirely that subtly breaks what you care about. When debugging regressions, my tool of choice is "git log -p". Sometimes commit messages help, but mostly they have been irrelevant, and only the actual diff matters. At best, they only show what the developer was thinking he was doing at the time. Sure, you can take time to make better commits, better commit messages and stuff, but by vehemently insisting on THE PROCESS and demanding documentation, an opus magnum of tests and a commit message each time, you exhibit traits of a control freak who wants to impose their OCD onto everyone else in the team. This is an area where diminishing returns kick in very quickly. I try to do better commits when I feel they are justified. When doing bugfixes, I describe what the error was, how I got to it, and why I think the fix is going to work. OTOH, I have learned to never demand — as long as code changes are sound, and as long as it's not so blatant as to look like a sabotage — form from my colleagues. I've learned that anyone who spends time nitpicking at the form in a PR, bickering over formatting and grammar and whatnot, is usually a shallow-minded prick with nothing to say about the content of the change. It's not worth it in the longer run.
- js2 4y ago
  I can only speak from my own experience. In my own experience, commit messages have saved me time. Documentation has saved me time. Not having had these things has sent me down hours long rabbit holes having to figure out why something existed. Reading the code doesn't tell me anything about why the developer did something a certain way, some important bit of context. Also in my experience, developers who don't explain anything in commit messages also don't explain anything in comments or elsewhere. So my day is spent encountering dozens of Chesterson's Fences. If those fences simply had a sign on them explaining why they were there I could more easily know whether they could be torn down. As a recent example, our macOS build hosts were running an alternate sshd on port 2222. Why was it there? What was wrong with using the sshd on port 22? If I tear it down and it doesn't seem to break anything, should I worry whether there's some use case I hadn't thought of? This alternate sshd was started by a shell script, so there was a place to add a comment saying why it was there, but there was no comment. The shell script was kept in git, but there was no explanation on the commit message or its PR. Eventually I was able to track down that it was due to a bug in Xcode that hadn't been relevant in over 5 years. However much time that developer saved by not documenting their work (a minute? 5 minutes?), I lost more than an hour having to figure out. I'll bet that developer is still going around not documenting their work and maybe they get promoting for shipping things fast. But then they move on and I get their mess.

by js2 4y ago

WesolyKubeczek 4y ago

> WesolyKubeczek, can I ask how long you've been a developer and what size projects you've worked on? Just over some 20 years. Haven't used RCS, but had some CVS and this version control system you have when you put file1.php, file2.php, file3.php, etc onto the production FTP, update includes, and hope you have caught all includes. Wasn't my idea, so don't ask. Codebases starting at several hundred thousand lines of code and up, mostly old ones. What I have learned is that given enough time, everything is a lie. Documentation is a lie probably as soon as you're writing it. Comments in the code are lies in a month. Commit messages are lies too, by the time you bisect some sonofabitch of a bug, the offending commit will point at something unrelated entirely that subtly breaks what you care about. When debugging regressions, my tool of choice is "git log -p". Sometimes commit messages help, but mostly they have been irrelevant, and only the actual diff matters. At best, they only show what the developer was thinking he was doing at the time. Sure, you can take time to make better commits, better commit messages and stuff, but by vehemently insisting on THE PROCESS and demanding documentation, an opus magnum of tests and a commit message each time, you exhibit traits of a control freak who wants to impose their OCD onto everyone else in the team. This is an area where diminishing returns kick in very quickly. I try to do better commits when I feel they are justified. When doing bugfixes, I describe what the error was, how I got to it, and why I think the fix is going to work. OTOH, I have learned to never demand — as long as code changes are sound, and as long as it's not so blatant as to look like a sabotage — form from my colleagues. I've learned that anyone who spends time nitpicking at the form in a PR, bickering over formatting and grammar and whatnot, is usually a shallow-minded prick with nothing to say about the content of the change. It's not worth it in the longer run.

js2 4y ago
I can only speak from my own experience. In my own experience, commit messages have saved me time. Documentation has saved me time. Not having had these things has sent me down hours long rabbit holes having to figure out why something existed. Reading the code doesn't tell me anything about why the developer did something a certain way, some important bit of context. Also in my experience, developers who don't explain anything in commit messages also don't explain anything in comments or elsewhere. So my day is spent encountering dozens of Chesterson's Fences. If those fences simply had a sign on them explaining why they were there I could more easily know whether they could be torn down. As a recent example, our macOS build hosts were running an alternate sshd on port 2222. Why was it there? What was wrong with using the sshd on port 22? If I tear it down and it doesn't seem to break anything, should I worry whether there's some use case I hadn't thought of? This alternate sshd was started by a shell script, so there was a place to add a comment saying why it was there, but there was no comment. The shell script was kept in git, but there was no explanation on the commit message or its PR. Eventually I was able to track down that it was due to a bug in Xcode that hadn't been relevant in over 5 years. However much time that developer saved by not documenting their work (a minute? 5 minutes?), I lost more than an hour having to figure out. I'll bet that developer is still going around not documenting their work and maybe they get promoting for shipping things fast. But then they move on and I get their mess.