5 ms·

> As a novice programmer, I was absolutely stunned that this was not standard practice. I agree with your point, and I will be benefit from this style if it we

> As a novice programmer, I was absolutely stunned that this was not standard practice. I agree with your point, and I will be benefit from this style if it were the standard, too. But don't you think a good community culture can make people maintain a good git history for this purpose? My daily job is a Linux kernel developer. I found that source codes are only the "What" part, git comments can and should state the "How/Why" part, and if all those still make no sense to me, I look for the original mailing list for the deeper "Why". Most of the time the information is sufficient.

nerflad 8y ago
Not all organizations have such robust communication structures, low levels of dysfunction, or git hygiene. Also, as mentioned, in a corporate environment where the software is proprietary and certain source files may sit dormant long enough for the original authors to move on from the company, it's important that they don't take the "how/why" part with them, so to speak, and leave the next maintainer SOL.
busterarm 8y ago
As much as I would implore you to document the why as a comment in the code after your experience, I have also learned the hard way that 'why' can be a moving target given enough time.
TeMPOraL 8y ago
I've never seen a git commit comment describing the "why" of code. "Added foo.\n\nImplemented az Bar because of blorgz." isn't nearly enough of a rationale, and that's the best description I see people making. Also, the whole point of putting something in a comment is that you have to read it when working through code around that comment. Putting a note in a commit log instead ensures that crucial information important to the code will not be visible, and most likely not read at all, when working on that code.
- jnurmine 8y ago
  Look at projects with high discipline and experience, such as the Linux kernel. You will find plenty of "why" examples. It seems to be easy to find plenty of projects with bad Git commits though. IMO the big architectural guidelines and structuring and other highest level things and API contracts etc. should be in an external file (not code). The high-level details around a certain implementation in the commit logs for that file/files. Relevant implementation details and important things in the code. The lower you go, the closer to a comment line in the code you should get. This reflects also the rigidity of the code: the high-level architecture should not change often; if it does, then the architecture is not really ready. Things should be certainly documented, but not in great detail inside the code files. The lack of documentation is in my opinion OK, the code is always the last word for how things actually work anyway. Misleading or wrong documentation are the absolute worst.
  - notacoward 8y ago
    The problem with trying to document anything in a commit message is that a commit message can't easily and unambiguously point to the specific section of code that each part of the commit message refers to. You can get general intent in a commit message, specific details in the code, and a yawning void in between. Sure, the back-and-forth on a mailing list or review system such as Gerrit can provide more of those direct links between code and explanation, but then it's often buried in a bunch of other discussion and dead ends. It's the "oh noes, comments can become out of date" times ten, so hardly a good alternative. And even when that's not the case, it's a horribly context-switchy way to get that information. Separating the explanation and the concrete expression just isn't a great idea. Funny how many people who would rather die than write a design spec also suggest that an even greater separation is a good thing.
    - dwild 8y ago
      > it's often buried in a bunch of other discussion and dead ends If your "why" doesn't contains this, I have an hard time understanding why you want it in the first place. The "why" is important to not make the same mistake. Theses others discussions and dead ends are all related to the issue, they are all questions that was asked/answered during it, they are all mistakes that may have been made. Personally every time I only needed a tiny bits more context, the commit message was enough and if I needed more, the full related ticket was essential (and not a simple why, but the full though process that became that decision). > Funny how many people who would rather die than write a design spec I'd rather die than lose time over something I consider won't save time in the long term. Writing any documentation is long and if that time is longer than the few time we'll need it, it's a loss of time. It's pretty rare that we need to go back to that information, when we do, the ticket information is enough and if it's not, doing the though process a second time isn't so bad the rare time it happens (which will provide more context by the new ticket discussion too). For sure if your ticket just say: - Break when we enter text - FIXED You are going to have a pretty bad time and you need to change that.
- ptyyy 8y ago
  Seen from our offshore with regularity: > Minor fix > Showing 6 files with 171 additions and 203 deletions
Cthulhu_ 8y ago
I think both comments and Git messages will depend on culture; in my local / current software development culture, an emphasis is put on the code being readable enough to be obvious (this isn't true by the way, even if it's good code). Nobody reads comments, nobody reads git history - mostly because they will always be outdated / no longer relevant. The assumption is that the original author knew what he was doing, and if not, there was a code review and anyone can fix it if they see a problem. Finally, it's code that probably won't be around anymore five years down the line, so detailed commit messages etc feel like a waste. (Mind you, I don't agree with the above. At the same time, I don't want to do this type of meaningless throwaway work anymore)
garmaine 8y ago
The project I'm working on has over 150 commits per day. It would take literally months of work to get up to speed with the codebase if you did it by reading just the git headers, not the diffs. This is considered a small project. Histories of active projects grow with age. A well maintained artifact should plateau in complexity.

nerflad 8y ago

Not all organizations have such robust communication structures, low levels of dysfunction, or git hygiene. Also, as mentioned, in a corporate environment where the software is proprietary and certain source files may sit dormant long enough for the original authors to move on from the company, it's important that they don't take the "how/why" part with them, so to speak, and leave the next maintainer SOL.

busterarm 8y ago

As much as I would implore you to document the why as a comment in the code after your experience, I have also learned the hard way that 'why' can be a moving target given enough time.

TeMPOraL 8y ago

I've never seen a git commit comment describing the "why" of code. "Added foo.\n\nImplemented az Bar because of blorgz." isn't nearly enough of a rationale, and that's the best description I see people making. Also, the whole point of putting something in a comment is that you have to read it when working through code around that comment. Putting a note in a commit log instead ensures that crucial information important to the code will not be visible, and most likely not read at all, when working on that code.

jnurmine 8y ago
Look at projects with high discipline and experience, such as the Linux kernel. You will find plenty of "why" examples. It seems to be easy to find plenty of projects with bad Git commits though. IMO the big architectural guidelines and structuring and other highest level things and API contracts etc. should be in an external file (not code). The high-level details around a certain implementation in the commit logs for that file/files. Relevant implementation details and important things in the code. The lower you go, the closer to a comment line in the code you should get. This reflects also the rigidity of the code: the high-level architecture should not change often; if it does, then the architecture is not really ready. Things should be certainly documented, but not in great detail inside the code files. The lack of documentation is in my opinion OK, the code is always the last word for how things actually work anyway. Misleading or wrong documentation are the absolute worst.
- notacoward 8y ago
  The problem with trying to document anything in a commit message is that a commit message can't easily and unambiguously point to the specific section of code that each part of the commit message refers to. You can get general intent in a commit message, specific details in the code, and a yawning void in between. Sure, the back-and-forth on a mailing list or review system such as Gerrit can provide more of those direct links between code and explanation, but then it's often buried in a bunch of other discussion and dead ends. It's the "oh noes, comments can become out of date" times ten, so hardly a good alternative. And even when that's not the case, it's a horribly context-switchy way to get that information. Separating the explanation and the concrete expression just isn't a great idea. Funny how many people who would rather die than write a design spec also suggest that an even greater separation is a good thing.
  - dwild 8y ago
    > it's often buried in a bunch of other discussion and dead ends If your "why" doesn't contains this, I have an hard time understanding why you want it in the first place. The "why" is important to not make the same mistake. Theses others discussions and dead ends are all related to the issue, they are all questions that was asked/answered during it, they are all mistakes that may have been made. Personally every time I only needed a tiny bits more context, the commit message was enough and if I needed more, the full related ticket was essential (and not a simple why, but the full though process that became that decision). > Funny how many people who would rather die than write a design spec I'd rather die than lose time over something I consider won't save time in the long term. Writing any documentation is long and if that time is longer than the few time we'll need it, it's a loss of time. It's pretty rare that we need to go back to that information, when we do, the ticket information is enough and if it's not, doing the though process a second time isn't so bad the rare time it happens (which will provide more context by the new ticket discussion too). For sure if your ticket just say: - Break when we enter text - FIXED You are going to have a pretty bad time and you need to change that.
ptyyy 8y ago
Seen from our offshore with regularity: > Minor fix > Showing 6 files with 171 additions and 203 deletions

Cthulhu_ 8y ago

I think both comments and Git messages will depend on culture; in my local / current software development culture, an emphasis is put on the code being readable enough to be obvious (this isn't true by the way, even if it's good code). Nobody reads comments, nobody reads git history - mostly because they will always be outdated / no longer relevant. The assumption is that the original author knew what he was doing, and if not, there was a code review and anyone can fix it if they see a problem. Finally, it's code that probably won't be around anymore five years down the line, so detailed commit messages etc feel like a waste. (Mind you, I don't agree with the above. At the same time, I don't want to do this type of meaningless throwaway work anymore)

garmaine 8y ago

The project I'm working on has over 150 commits per day. It would take literally months of work to get up to speed with the codebase if you did it by reading just the git headers, not the diffs. This is considered a small project. Histories of active projects grow with age. A well maintained artifact should plateau in complexity.