4 ms·

My perfect commits have message „WIP on stuff”, include changes to code coupled with formatting changes, have zero tests, nada documentation, and no links to is

My perfect commits have message „WIP on stuff”, include changes to code coupled with formatting changes, have zero tests, nada documentation, and no links to issues. But they are perfect nevertheless, because I judge them so. And because the code works. Also, because I get to get out more.

simonw 4y ago
This post was extracted from a talk I gave at DjangoCon a few weeks ago, which was about how this kind of workflow has /increased/ my personal productivity by a material amount. https://github.com/simonw/djangocon-2022-productivity https://github.com/simonw/djangocon-2022-productivity So I get to get out more because I'm doing this!
- WesolyKubeczek 4y ago
  You may think so ;)
airstrike 4y ago
I feel seen
js2 4y ago
I wanted to get out today, but instead I spent two hours debugging an issue because I was dealing with code from someone who thought like you who didn't think documentation, comments, meaningful commit messages, or tests were a good use of their time. I don't care what you do with your code, but as soon as someone else inherits it, you're a sociopath if you didn't document anything along the way. And btw, the person who inherits that code may be your future self, and you'll thank your past self for writing down why you did something the way you did.
- WesolyKubeczek 4y ago
  Do you think I should also document all the bugs I put in my code? If I knew they were bugs, I wouldn’t be putting them there in the first place. I may be crazy, but a moron I’m not.
  - 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.
    - 4y ago
DangitBobby 4y ago
I honestly feel that any sort of documentation in commits themselves (besides a short, concise summary of what and maybe why) is a waste. It's one of the least likely places people will be looking for that information. A better place is in comments near the code, though obviously that has its own issues.
- ziml77 4y ago
  I agree. It's much better to just have all of the key info inline. If I look at the commit history of a file, there's going to be such a mess of irrelevant commit messages to the issue I'm looking at that it's hardly worth spending the time trying to find if the info is there.

simonw 4y ago

This post was extracted from a talk I gave at DjangoCon a few weeks ago, which was about how this kind of workflow has /increased/ my personal productivity by a material amount. https://github.com/simonw/djangocon-2022-productivity https://github.com/simonw/djangocon-2022-productivity So I get to get out more because I'm doing this!

WesolyKubeczek 4y ago
You may think so ;)

airstrike 4y ago

I feel seen

js2 4y ago

I wanted to get out today, but instead I spent two hours debugging an issue because I was dealing with code from someone who thought like you who didn't think documentation, comments, meaningful commit messages, or tests were a good use of their time. I don't care what you do with your code, but as soon as someone else inherits it, you're a sociopath if you didn't document anything along the way. And btw, the person who inherits that code may be your future self, and you'll thank your past self for writing down why you did something the way you did.

WesolyKubeczek 4y ago
Do you think I should also document all the bugs I put in my code? If I knew they were bugs, I wouldn’t be putting them there in the first place. I may be crazy, but a moron I’m not.
- 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.
  - 4y ago

DangitBobby 4y ago

I honestly feel that any sort of documentation in commits themselves (besides a short, concise summary of what and maybe why) is a waste. It's one of the least likely places people will be looking for that information. A better place is in comments near the code, though obviously that has its own issues.

ziml77 4y ago
I agree. It's much better to just have all of the key info inline. If I look at the commit history of a file, there's going to be such a mess of irrelevant commit messages to the issue I'm looking at that it's hardly worth spending the time trying to find if the info is there.