Linus Torvalds: 'I Do No Coding Any More' • Hacker News Board

Re: Linus Torvalds: 'I Do No Coding Any More'

#141

Post by aaomidi » Sun, Jul 05, 2020, 7:47 PM UTC

dasil003 wrote: post #26

> commit messages to me are almost as important as the code change itself This is high on my list of code craftsmanship points. It's very difficult to explain to young programmers who have never worked on an old code base how valuable this is when done well. In fact, often you hear complaints about how a code base "is crap", but more often than not I'd wager this is just a result of the context at the time not being…

Until you use squash and merge. Suddenly commit messages become far less helpful.

Re: Linus Torvalds: 'I Do No Coding Any More'

#142

Post by Matthias247 » Sun, Jul 05, 2020, 7:52 PM UTC

systemvoltage wrote: post #103

mrisoli wrote: post #92

Earlier quoted context omitted.

I write detailed commit messages for every single commit I make(even though commits would be squashed on merges), I write detailed PR descriptions that included before/after screenshots in multiple resolutions whenever relevant. Never once did I have any indication that someone took their time to read descriptions or commit messages. In my previous job, I received some feedback from my manager that some people compla…

Yep, no one ever reads them and the cost to benefit ratio is extremely low. Writing good comments is far more important. Don't explain what the code does - that's what the code is for, explain the why and the background information in the code. Additional, explain what the code does at the function level or at the module level - at a much higher abstraction level basically than the line of the code. No one ever looks…

> Yep, no one ever reads them and the cost to benefit ratio is extremely low

I read them quite often. Whenever there is a regression detected between 2 software revisions that have been deployed somewhere the first thing I do is checking commits and commit messages for packages that have changed to find the more obvious reasons for a behavior difference. Checking code diffs at that point would be a lot more effort.

Re: Linus Torvalds: 'I Do No Coding Any More'

#143

Post by tmh88j » Sun, Jul 05, 2020, 7:54 PM UTC

nemetroid wrote: post #137

tmh88j wrote: post #125

Earlier quoted context omitted.

You seem to be confusing end user documentation with code documentation....an actual document that describes how to use the software vs comments in the code that describes how it works >Sometime later, a new use case ”C” is added to the requirements, and this particular part of the code happens to already support C without making any changes. Can you give an example of a new use case being introduced without the code…

I’m not confusing anything, but I’m using the term ”use case” in a very broad sense. > Can you give an example of a new use case being introduced without the code changing? I once wrote a framework for processing data in different proprietary formats from different vendors into a unified format. At first, each vendor had its own code module, and any idiosyncrasies between different data files for a given vendor were…

>That’s what I’m asking you! :)

As I've been saying comments in the code should describe how that specific section of code works, and why it's done that way if the "how" isn't enough. The new parts of the codebase would have comments describing how that code works. The unchanged code still functions as it always did. There's no reason to make comments on how another part of the codebase works. Code comments shouldn't be architectural descriptions of an entire codebase.

Re: Linus Torvalds: 'I Do No Coding Any More'

#144

Post by pcl » Sun, Jul 05, 2020, 7:55 PM UTC

jacquesm wrote: post #130

pcl wrote: post #117

Earlier quoted context omitted.

I consider the version control history to be part of the code. I put docs into the source tree (sometimes in the form of comments; sometimes in dedicated doc files) for things that are suited to live next to the code, but often my commit messages contain more discussion of what used to be and why I chose a certain implementation approach. I generally think that documentation in code should describe what the code does…

Code tends to live longer than the VCS that stores it. I've seen more than one VCS migration that ended up losing a lot of the history of how things got to be where they are today.

I guess I’m an optimist on that front. I’ve lost history from CVS and SCCS, but not from SVN, Perforce, Git or Mercurial, including a number of Git module extractions. I think that history-losing version control migrations are a thing of the past.

Re: Linus Torvalds: 'I Do No Coding Any More'

#145

Post by mehrdadn » Sun, Jul 05, 2020, 7:57 PM UTC

dcow wrote: post #140

mehrdadn wrote: post #128

Earlier quoted context omitted.

How do you convince other people of this though? That's been what I've struggled with. I hate squashing too, but I can't convince anybody.

I like to remind people that pull requests are an abstraction over a set of commits. I show people that they can click on each individual commit in a PR and see the granular delta. Surprisingly often I’ve learned that people really don't know you can do this! If they argue that you cant revert entire features remind them that merge commits are a thing. If they don't like lots of merge commits littering the history su…

> If your team insists on 1 PR == 1 commit

Yeah that's the scenario I'm thinking about. The trouble I have with this is two things:

- People inherently don't make the PRs as granular as a commit would be, because it puts load on other processes (like CI, review overhead, etc.) and slows things down that way. So you end up with PRs that are hundreds of lines instead of self-contained commits that are dozens of lines long (or less). They still fit under the same goal (and hence PR), but aren't as granular as they could/should be, which makes them harder to revert.

- It's far easier for people not to care about their commit messages and commit granularity than to care, and honestly, with CLI tooling, I can't claim it's easy. I use TortoiseGit and rebase all the time to keep my commits organized, and it's far easier for me to shuffle around commits that way, though it's still non-negligible overhead.

On the other hand, CI is precisely one argument I get for squashing: because rebasing/merging would imply some commits are untested, others specifically don't want them in the tree (they find it misleading when they bisect). I don't really find this compelling—I find it harmful to lose so much granularity information just because you didn't run a test against it (especially when it's already not the case that every commit passes all the tests) because it makes it impossible to look back and revert a tiny commit later, but I can't really convince others the trade-off is worth it. And to make this work well and keep a good history, you need to rebase to specifically avoid spurious commits like "fixed lint" or "removed whitespace", which generates additional overhead (and makes for harder reviewing when you rebase).

My position is it should be up to the author to decide whether a PR should be merged/squashed/rebased, because the answer can be different in different situations and the author would know best, but I have a hard time convincing anybody... people would rather have a uniform workflow instead.

Re: Linus Torvalds: 'I Do No Coding Any More'

#146

Post by jacquesm » Sun, Jul 05, 2020, 8:00 PM UTC

pcl wrote: post #144

jacquesm wrote: post #130

Earlier quoted context omitted.

Code tends to live longer than the VCS that stores it. I've seen more than one VCS migration that ended up losing a lot of the history of how things got to be where they are today.

I guess I’m an optimist on that front. I’ve lost history from CVS and SCCS, but not from SVN, Perforce, Git or Mercurial, including a number of Git module extractions. I think that history-losing version control migrations are a thing of the past.

Check out a 'zip' file to cross port to a system that does not support your VCS of choice (many embedded systems, for instance) and poof half your docs are gone... VCS should store the code, commit messages should aid in bi-secting but should not explain too much other than to clearly document what was changed in that commit with reference to a particular ticket if available. That way you keep the meta stuff in one place and all the action where the code itself lives, and where you are most likely to need it.

I'm a big fan of literate programming, and VCS is not an integral part of that.

Re: Linus Torvalds: 'I Do No Coding Any More'

#147

Post by u801e » Sun, Jul 05, 2020, 8:03 PM UTC

mrisoli wrote: post #92

dasil003 wrote: post #26

> commit messages to me are almost as important as the code change itself This is high on my list of code craftsmanship points. It's very difficult to explain to young programmers who have never worked on an old code base how valuable this is when done well. In fact, often you hear complaints about how a code base "is crap", but more often than not I'd wager this is just a result of the context at the time not being…

I write detailed commit messages for every single commit I make(even though commits would be squashed on merges), I write detailed PR descriptions that included before/after screenshots in multiple resolutions whenever relevant. Never once did I have any indication that someone took their time to read descriptions or commit messages. In my previous job, I received some feedback from my manager that some people compla…

> Never once did I have any indication that someone took their time to read descriptions or commit messages.

Just because others don't use a tool for documenting code doesn't mean the tool shouldn't be used. I make sure the team I work with documents the what was done and why in their commit messsages. I also make sure that, when applicable, they describe the bug that was fixed and how it was fixed in the commit, or how performance was tested by applying a certain fix in the commit message.

Several times over the years, people have gone back to those commit messages by finding them via git blame and figuring out what was done months or years ago and preventing regressions by reading the commit messages.

> Never once did I have any indication that someone took their time to read descriptions or commit messages.

I do admit that I have been tempted to do things like:

git commit --allow-empty-message

for changes and see if anyone would notice.

Re: Linus Torvalds: 'I Do No Coding Any More'

#148

Post by u801e » Sun, Jul 05, 2020, 8:04 PM UTC

systemvoltage wrote: post #103

mrisoli wrote: post #92

Earlier quoted context omitted.

I write detailed commit messages for every single commit I make(even though commits would be squashed on merges), I write detailed PR descriptions that included before/after screenshots in multiple resolutions whenever relevant. Never once did I have any indication that someone took their time to read descriptions or commit messages. In my previous job, I received some feedback from my manager that some people compla…

Yep, no one ever reads them and the cost to benefit ratio is extremely low. Writing good comments is far more important. Don't explain what the code does - that's what the code is for, explain the why and the background information in the code. Additional, explain what the code does at the function level or at the module level - at a much higher abstraction level basically than the line of the code. No one ever looks…

> No one ever looks at the commit messages when trying to figure out what the code does as it convolves history and state of the repository

Do people not use git blame to check what they're changing before they change it? That's how I check the history around the changes I'm going to make before I make them.

Re: Linus Torvalds: 'I Do No Coding Any More'

#149

Post by mamon » Sun, Jul 05, 2020, 8:16 PM UTC

mister_hn wrote: post #105

dasil003 wrote: post #26

> commit messages to me are almost as important as the code change itself This is high on my list of code craftsmanship points. It's very difficult to explain to young programmers who have never worked on an old code base how valuable this is when done well. In fact, often you hear complaints about how a code base "is crap", but more often than not I'd wager this is just a result of the context at the time not being…

I've worked with 20yrs+ senior Devs whose commit message is always something like 1 or 2 words sentence (think of "cleanup", "feature X done") and some of there work manually with diff-tools between their local copy of code and the for repository they check out on a different folder. If they're not satisfied with the incoming changes, they just overwrite them and push the overwrite back to repository. This has happen…

In theory, this could still work if one of those two words put in by lazy developers was a JIRA ticket number where all the details are described in length. Atlassian stack (JIRA, Bitbucket, etc.) even allows you to make those clickable links.

Re: Linus Torvalds: 'I Do No Coding Any More'

#150

Post by nemetroid » Sun, Jul 05, 2020, 8:17 PM UTC

tmh88j wrote: post #143

nemetroid wrote: post #137

Earlier quoted context omitted.

I’m not confusing anything, but I’m using the term ”use case” in a very broad sense. > Can you give an example of a new use case being introduced without the code changing? I once wrote a framework for processing data in different proprietary formats from different vendors into a unified format. At first, each vendor had its own code module, and any idiosyncrasies between different data files for a given vendor were…

>That’s what I’m asking you! :) As I've been saying comments in the code should describe how that specific section of code works, and why it's done that way if the "how" isn't enough. The new parts of the codebase would have comments describing how that code works. The unchanged code still functions as it always did. There's no reason to make comments on how another part of the codebase works. Code comments shouldn't…

Then perhaps we have different definitions of what "why" comments are. The usual reason we write code is to solve (business) problems, so to me, "why" implies a connection to business requirements. So even though

> The unchanged code still functions as it always did.

...the why of that unchanged code, i.e. the reason it exists at all, may change. And for that reason, the "why" (the business reasons) should not be in the code.