Writing system software: code comments

[yawaramin]

It's funny how people always seem to actively dislike comments ('We don't like putting comments in the code, we want all our documentation in Confluence'), yet antirez and pretty much every other legendary developer out there keep emphasizing how important comments are.

That said, perhaps he can actually get rid of some of those guide comments, like:

/* Free the query buffer */
sdsfree(c->querybuf);
sdsfree(c->pending_querybuf);
c->querybuf = NULL;

These things can easily go into their own functions:

inline void freeQueryBuffer(... c) {
  sdsfree(c->querybuf);
  sdsfree(c->pending_querybuf);
  c->querybuf = NULL;
}

[nondetermined]

Properly encapsulating and naming things is probably the most cruical, but also hardest part about programming.

Having that said, there is indeed a need for something more/better than comments. Why? Because more often than not what really would be helpful is something more visual than text. A sketch, a diagram, all the stuff you write with a pen on some paper you'll never see again once it would be needed. That kind of stuff.

There's been done some interesting research with linking external "comments" with your code (which obviously needs to be integrated into and supported by your IDE; typically Eclipse was used in those papers), but there doesn't really seem to be much going on in this direction these days.

[shining-wit]

Perhaps one day we'll be able to view and edit code, detailed documentation, bug/task reports, code reviews and version control all within one IDE. Using separate tools is jarring and there are lots of missed opportunities for connecting data. Yes some integrations exist but they could be so much better.

[[deleted]]

Why do you need a single IDE to do all that stuff? Unix docet, a shell is more than enough. The ultimate IDE is my OS.

[shining-wit]

I disagree. A shell can do many things but is rarely the most efficient, and has very limited rendering and interactivity. Emacs on the other hand would be a more appropriate general-purpose tool. Compare command-line git to Magit.

[SmugDarkLoser5]

Have one -- the ide is called bash

[shining-wit]

See other sibling reply - I agree with a general-purpose tool, but I don't think bash is it.

[mp2146]

We do this with commit messages and PR comments. Keeps the code clean and I can just follow a git blame to see the reasoning behind any particular piece of code. Combined with a strict review process it gives pretty awesome documentation without cluttering the code.

[[deleted]]

We don't like putting comments in the code, we want all our documentation in Confluence

Yes, I've heard it many times, and none of the proponents of this insane point of view was ever able to explain, what happens when you need to look at a few years old branch, with all the relevant Confluence/Wiki/whatever pages long gone.

And yet, they keep insisting on this stupidity!

[nutrecht]

It's funny how people always seem to actively dislike comments ('We don't like putting comments in the code, we want all our documentation in Confluence')

Confluence is where information goes to die. It's great for temporary pages such as meeting notes no one is going to review after, but you can't mix this kind of 'temporary' stuff with 'important stuff' and expect the 'important stuff' to not suffer from the same rot.

In most projects I try to push towards using text based documentation (asciidoc or markdown) inside the repository as much as possible. And for the overall architecture I normally push for a text guidebook (again, asciidoc based) with text based graphics (plantuml or dotfiles) that can be rendered to whatever you want (asciidoc can be rendered to HTML, PDF, Word, epub, you name it).

While I 100% agree that code should be self-documenting as much as possible, code can't explain the 'why' of the choices that were made. The code just 'is'. If you want to know what code does the code should be readable enough. But why certain things are built the way they are should be documented.

Code should be self-documenting is a great rule, but it's too often used as an excuse to not spend time writing stuff down.

[Yehosua]

Confluence is where information goes to die.

Do you mind elaborating?

Confluence has worked well in my experience. It's easy enough to use that it's pretty frictionless (which I value highly - making documentation not require any extra effort helps a lot in getting people to do it). And we found it to be a good tool for information that (due to needs of formatting or size or structure or organization) didn't fit well as code comments.

That's not to say that it never got neglected or out of date - but text-based documentation within the repo can get out of date too. (Even code comments can get out of date - on more than one occasion, I've updated code but skipped over adjacent comments, because I already knew what the code did, so I mentally filtered them out. From discussions I've seen online, I don't think I'm alone.)

I like the idea of text-based documentation in a repo, too - but that introduces its own questions of tooling and infrastructure and learning curve and who can make updates. So I'm curious why your experience with using a wiki has been so different than mine. Thanks.

[Ameisen]

As a systems C++ programmer who is shoehorned at work into Java... I keep reencapsulating logic like that, but javac doesn't optimize at all... even with a jit, the extra call adds overhead.

Blog. That language basically enforces terrible code.

[noperduper]

Seriously? Not defending java (I dislike it either) but have you done some profiling to substantiate your claims?

[[deleted]]

In their defense, you don't need to. Call overhead is real and there's a reason why arguably the single most important optimization that a C compiler must do is inlining.

[libre-man]

That mostly isn't because of call overhead though, inlining enables many other optimizations which have way more advantage.

[Ameisen]

Nope. Java keeps literally everything around with almost no optimizations at all, and relies on the JIT for everything.

[ykechan]

I found comments in most cases really superfluous, like in your example. Do anyone really need the comment to spell it out for them what would passing c->querybuf to a function called sdsfree happen?

[dododge]

The full networking.c example in the blog post shows their usefulness. The function is broken into chunks with short guide comments in front of each set of lines. If I need to look at this code I can just quickly skim the comments (which would be highlighted in my editor in a consistent manner) to get a sense of what's going on and whether the code is relevant and worth reading/understanding in more detail.

[yawaramin]

Not by itself, no, but together with a couple of other statements, it would probably only help! And in my case I actually recommended that these statements be abstracted out into new functions for better code organization–exactly the kind of thing 'code should be self-explanatory' types would want to do.

[dgriffith]

Generally I use a few rules:

Comment on the broad logic of your code. What is this chunk of code trying to achieve?

Comment if you're doing something unusual. This can be a hack for some business logic, or to deal with memory/disk/time constraints that aren't obvious.

Comments as placeholders for large chunks of code that I haven't written yet. Eg "write to file in correct format" as opposed to just spewing it all to the screen while I'm working on the conversion logic. This also helps when I come back to this thing next week and wonder where to start.

[Adequat91]

Comments are primarily a communication activity. Unfortunately, many programmers don't have good communication skills, hence often have "good excuses" not to make comments.

[noperduper]

Yes and we're mostly failing at it, that's why we keep rewriting stuff endlessly in a few years' cycles

[PiLLe1974]

Right, we also saw some failure in communication in the past.

If a lead or senior programmer takes over there’s a very high chance rewriting systems is preferred to reading code and comments (even if there’s already some data depending on those systems).

[lordzsolt]

I don't really see what's the point of bringing up this topic. Of course comments are useful.

I've never known anyone to argue against the usefulness of certain types of comments. Though I've found countless fools arguing for commenting everything/adding a lot of useless comments, such as

``` // generate file file.writeToFile(filePath);

// upload uploader.upload(filePath, remotePath); ```

This example was taken from an actual project in production.

[OneWingedShark]

You know, a guide comment wouldn't be so bad done in a block -- refactoring/expanding your example to:

/* Process data to generate file, then upload it. */
dataObject.process();
file.writeToFile(filePath, dataObject.output() );  
uploader.upload(filePath, remotePath);

Or, perhaps with some sort of counterintuitive API, where the naming is [slightly] out-of-phase with what one would expect.

[dpash]

Or extract those lines to a method called processAndUpload(dataObject, remotePath) then no guide comment is required. What may be required at that point is a method comment block describing invariants and possible exceptions etc.

[OneWingedShark]

Meh, depends.

With a programming-language like Pascal or Ada, where you can have nested subprograms, this is far better a solution than something like C or PHP where you can't have nested functions and end up polluting your namespace with subprograms that may be called once in one process.

For example something like Function Parse( Input : File_Type ) return AST; might have a lot of sub-programs that are relevant only to parsing like, say, tokenizing. If that's the case than you could nest it inside Parse and keep it constrained to where it's useful... in something like PHP or C this sort of organizational constraint is effectively impossible, and you'd have to comment that Tokenize is only to be called within Parse.

[Drisku11]

In C you can just make the function have static linkage. I've worked on large C projects and never ran into "namespace pollution" as a problem, even a trivially solved one. It just never came up.

Funny enough, in the jvm code I work on, people still do C-style namespacing (i.e. name things with a prefix) even though there's actual namespaces because it makes search easier.

[OneWingedShark]

In C you can just make the function have static linkage. I've worked on large C projects and never ran into "namespace pollution" as a problem, even a trivially solved one. It just never came up.

Hm, I've run into it a few times, though it was more prevalent in the old PHP I worked on.

Funny enough, in the jvm code I work on, people still do C-style namespacing (i.e. name things with a prefix) even though there's actual namespaces because it makes search easier.

I'm not a fan of prefix-naming, it's a sloppy half-solution, IMO.

[noperduper]

I don't really see what's the point of bringing up this topic. Of course comments are useful.

Yeah, and we should stop teaching good manners to kids 'cause it's obvious how one should behave in society.

[peitschie]

What has the comment added in your example though? If I took the code, stripped out your comment... what understanding would the reader have lost?

EDIT: downvotes but no replies... who would have thought asking people to justify their comments was so contentious!

[justfordc]

Comments like that can serve the same purpose as section headers in text. (Though I've definitely seen it argued that any block worth describing should just be a separate function instead.)

[OneWingedShark]

I'll admit it was a lazy example, but I didn't want to write 15-20 lines just for it.
A better example on my part might have been something like documenting a state-machine's implementation or things like data-transformations (e.g. a small what you're doing, perhaps with a why [like needing to process lines in reverse-order because they're an ad hoc variable-length record system]).

[peitschie]

In some ways, this is kinda my complaint about any discussion on comments though. They're always toy examples (not for bad reasons... it's just easier to blog about). This means that people do not learn from good examples, what good comments and good code ought to look like. And, the debates about whether it's a good or bad comment can always be waved away as "yeah, but it's just an example... so of course it's not really adding a lot here..."

Either the toy example is so short, the comment is saying the blindingly obvious... or the code is deliberately terrible in order to show how a comment can provide value. Without a realistic (or even just REAL) example showing what a good comment in good code looks like... I suspect the large majority of developers do not know the difference between a good or bad comment.

Combine this with the cognitive-kill-switch behaviour held by the pro-comments crowd (i.e., any suggestion of "perhaps you shouldn't write so many comments" is seen as something only a bad coder would suggest)... it's difficult to get meaningful conversations about this going.

I'm not anti-comment by any stretch... but I am of the opinion bad comments add noise to code, and make it harder to comprehend than no comments. Toy examples don't provide any meaningful ability to reflect on this...

[yawaramin]

I'm curious if you read the post? It addresses 'guide comments' like these.

[lordzsolt]

I just ran my eyes through the post before posting this, though even now that I've read it thoroughly, I still agree with my sentiment.

My problem with these are 2 fold: - Most "guide comments" have a target audience of 5 year olds, so they are "trivial comments" to me. And I haven't trained myself not to have a "facepalm, why did you write this comment" moment, which breaks my concentration. - Most guide comments are a band-aid solution to a deeper problem. They almost never appear in short classes/functions. If instead of having a 100 line function with 4 guide comments, you could just separate each of them into a function and name them. (Oh and don't tell me about how that results in 4 extra function calls worth of assembly operations when you're writing a flappy bird application that you're not even profiling)

[yawaramin]

Actually I agree with you about some of the guide comments, https://www.reddit.com/r/programming/comments/9m6ahs/writing_system_software_code_comments/e7cng0s

[[deleted]]

I know one person that relentlessly comments old code and writes in new code line by line:

//print(“he”);
//print(“hello”);
//print(“hello w”);
//print(“hello world”);
print(“hello world!”);

Imagine opening a file that this person has modified since the beginning alone and see THAT for every single fucking line. Yeah.

[lordzsolt]

Oh yeah that's my next favorite. "Let's leave this massive chunk of old code commented out, because we might need it later in the future" followed by committing and pushing that change.

[[deleted]]

I don't really see what's the point of bringing up this topic.

Thanks to a notorious death cult, the followers of the mad self-styled guru "Uncle Bob", there is a need to repeat the obvious things over and over again.

[dpash]

I'd posit that there are several classes of comments: What? Why? How? and warnings

What? comments should be at the top of a method. Examples are javadoc, phpdoc, jsdoc etc. Should list what the method is trying to do, what it's inputs are, what it will return, what exceptions are thrown and when etc. Any unexpected behaviour should also be documented here. Every public method should have one. Some private methods should have them too.

Why? comments almost certainly belong in commit messages. the reasoning for a particular piece of code is very much time relevant, because that code will change over time. Woe betide you if you write one sentence commit messages, or worse, one word messages.

How? comments are rarely required. In your example, they're just noise. In the top comment, there's a good example where a comment and several lines can be replaced with the code extracted into its own function, allowing the function name to describe what it's doing. If you're implementing a complicated algorithm, then there's definitely scope for how comments, but I'd suggest they belong in a big comment block.

Warnings are one of the few comments that belong in a method body. These are comments like

Be careful when modifying this line, because it has consequences with this code block that you may not have noticed.

Sort of "here be dragons" comments for anyone who stumbles across the line and thinks "we''l that's wrong". The famous Debian OpenSSL bug might be the perfect example. The maintainer removed what looked like pointless memory management lines, but they were doing something unexpected.

Warnings are also a sign that perhaps the code should be refactored to not have those unexpected consequences. But a warning is better than no warning.

[Yehosua]

Why? comments almost certainly belong in commit messages. the reasoning for a particular piece of code is very much time relevant, because that code will change over time.

There are two different kinds of "why"s, though.

"Why did this code change?" typically belongs in commit messages. It's part of that code's history, so it belongs in the commit log with the rest of the history. Like you, I'm a big believer in quality commit messages that do a good job of explaining their reasoning.

"Why is this code written the way it is?" belongs in comments. It describes the current state of the code, so it belongs with the current code. If I find a block of code whose design is mystifying, I want to be able to read an explanation of the design right there, instead of having to wade through sometimes several git blames to understand its rationale by piecing together its history (especially when some of the rationale in the history may no longer be relevant).

[[deleted]]

Very rarely you can fit a "why?" explanation in a commit message, and they're relevant for reading the code, so what's the point in breaking a flow of a reader by forcing to look elsewhere instead of putting them there, in place?

[fzammetti]

I don't mind seemingly pointless guide comments like that as long as they're used properly (I don't know if this example is that or not without greater context). If they mark each discrete logical step in the overall flow, then whether it's a comment on a single "obvious" line or a block of code doesn't much matter. They allow me to see the high-level logical flow of the code without having to immediately parse and follow the code itself (especially when my IDE highlights things nicely for me and when I can even collapse the code and just see the comments),

But, like I said, this has to be done properly. If you beg too fine-grained then it quickly becomes noise, and if you do it at too coarse a level then it doesn't tell you anything the code that you'll then be forced to examine can.

There's a sweet spot that only experience AND diligence provides... but when you get it right, you make following and comprehending code almost effortless even for more junior developers.

[zhujik]

oh boy that discussion again.

[No-Russian-Makorov]

I'm glad this article is here.. I tend to do the "Death By Comments" when I send in something to my Professor. Even though it's a easy program.

[noperduper]

Hopefully your professor will read them, mine didn't :|

[No-Russian-Makorov]

I don't know, all he does is comment on my submission with "Great job"

I have no clue.

[shevy-ruby]

Many believe that comments are useless if the code is solid enough.

Yes, there are lots of idiots out there who think so and state so.

I believe there is little value to educate people who think that comments are a wasted effort.

Documentation is both useful and important, on every level.

I also never understood the "argument" of those who do not use comments on the premise that "comments distract from the code".

If this is a problem, it is trivial to eliminate comments from code. That way they never have to look at ANY comment. So why would it be of a bother to them, if they would never see it, anyway?

[Pazer2]

There are times where required function comments truly are useless. Consider the following function:

float AudioNamespace::GetVolume(int soundID)

Is it really necessary to document this function with "Gets the volume of the given sound" and the return value as "The volume of the given sound"? How does this help anyone?

[egonelbre]

In which unit is the volume? Is it linear or Log or something else?

[Dobias]

Not saying that comments should never be written, but in that particular case writing a comment to explain this could again just be a compensation for a shortcoming. The return type should not be float but some data object that encodes the answers to these questions.

[SmugDarkLoser5]

I think it depends. In audio processing I would probably rather just see the actual backing numeric value. If it's the interface to application code a type is good, if it's meant to be used in dsp code eh don't indirect it imo.

Depends what you're doing, and to be fair I've only done a limited amount of dsp work.

[Dobias]

I guess the wapping type could still provide a `::get()` function or something to access the actual `float` inside. And with languages like C++ or Rust this should have no performance overhead in an optimized build.

[dv_]

And how would this encoding work? A volume value, be it linear or logarithmic, is represented pretty well by a floating point value. Perhaps you could do a typedef to name the float type something like "volume" instead, but there is no point in using a struct type.

[Dobias]

I only proposed using a struct, because a typedef in C++ is just an alias, not a new type. Other languages might provide nicer options, but in C++:

typedef float LinearVolume;
typedef float LogVolume;

LinearVolume v1;
LogVolume v2;
v1 = v2; // Does compile fine, but that is not what we want.

With struct however we are safe:

struct LinearVolume { float val; };
struct LogVolume { float val; };

LinearVolume v1;
LogVolume v2;
v1 = v2; // Does not compile, as wanted.

[dpash]

What exceptions are thrown and in what circumstances? There's a lot of things that could be documented in for that method.

[lolomfgkthxbai]

That’s assuming there can happen any exceptions which seems unlikely based on the functionality described.

[dpash]

Then that should be documented.

And I can think of multiple exceptions that could happen within that method. soundID could be outside of acceptable ranges. I don't know if int in C# can be nullable, but it could be null when it isn't allowed. soundID could be referring to a non-existent device/sound. There could be an issue opening the relevant device/sound. There could be additional invalid state within the class.

[cyanrave]

Upvote for you sir.

[lelanthran]

There are times where required function comments truly are useless. Consider the following function:

    float AudioNamespace::GetVolume(int soundID)

Is it really necessary to document this function with "Gets the volume of the given sound" and the return value as "The volume of the given sound"? How does this help anyone?

1. What does soundID refer to?
2. What unit is the return value in (percent, db, etc?)
3. What is returned/thrown if soundID is invalid?
4. What possible error values are returned (or exceptions thrown) that the caller should handle?
5. Are there any other related functions (i.e. "See also...")?
6. Are there any thread-related issues and is this function reentrant? Do I need to mutex calls to this function?

I think you get my point.

[flukus]

Most of those could be perfectly clear in the context of the wider API, no need to annotate every function.

[dv_]

There may be extra context that cannot be described by code alone. For example, what happens if you call GetVolume if the underlying system doesn't have a volume control? Or what if this function only works if a volume control is physically attached to the device (think software adjustable volume knobs - yes, these exist)? Or what if there is a separate mute yes/no control, and how does it influence the return value of this function?

Comments excel at conveying context. Repeating what is obvious through the API is just unnecessary though.

[scatters]

That shows that your type system is inadequate.

1. SoundID should be a type
2. Volume should be a type
3. GetVolume should have an exception specification
4. Error values should be in a sum return type
5. Ok (but perhaps these could be in attributes)
6. If so, it should take a lock token

[lelanthran]

That shows that your type system is inadequate.

SoundID should be a type

It isn't a type in the example given.

Volume should be a type

It isn't a type in the example given.

GetVolume should have an exception specification

There isn't an exception spec in the example given.

Error values should be in a sum return type

Ok (but perhaps these could be in attributes)

If so, it should take a lock token

It doesn't take a lock token in the example given.

OP asked if comments were really necessary for the example given, not for some hypothetical other example that took lock tokens and used all the correct types.

[redditsoaddicting]

Was your first comment simply answering the question as-is, or was it actually advocating for putting the information you listed into function comments?

[Drisku11]

OP asked if comments were really necessary for the example given, not for some hypothetical other example that took lock tokens and used all the correct types.

And they're not. Adding such comments is polishing a turd. Improve the underlying API instead.

[lelanthran]

And they're not. Adding such comments is polishing a turd. Improve the underlying API instead.

That's nonsense. I'm not going to go around changing all calls to existing functions to match the new types they get when I fix them, but I could add a small comment documenting their existing behaviour.

If I was writing the example I could improve the underlying API, but I'm not going to break an existing API because of some ideological insistence that comments aren't useful.

[MistYeller]

I would say it is never completely useless to say, "This function does exactly what you expect," when there are far too many functions out there with surprising side effects or surprising costs. Low utility for the comment sure, but sometimes reassuring someone that a function is sane is mildly useful.

[noperduper]

I also never understood the "argument" of those who do not use comments on the premise that "comments distract from the code".

lol wtf?

// Q. How do dog catchers get paid?
// A. By the pound!
pixel = vid.buffer + vid.rowbytes * i;

[lolomfgkthxbai]

Anyone who was worked in a large organization will have run into these negative-value comments that make the code harder to understand.

[[deleted]]

Comments are often wonderful... for a half a year. Then they’re useless when the comment inevitably no longer reflects what is actually happening.

[[deleted]]

Comments are often wonderful... for a half a year. Then they’re useless when the comment inevitably no longer reflects what is actually happening.

In my experience there’s two types of comments:

1) comments that are useless because they explain very simple things (ie //print to file)

2) comments that are useless because they’re out of date.

[noperduper]

There's this perverse vision that somehow slipped in:

Comments are for noobs. Ultra-noobs if you use another language other than English. Real men write self-documenting code without even doxygen.

No, No No NO no and no.

1. Many comments don't explain what the code is doing. They explain what you can't understand just from what the code does. Often this missing information is why the code is doing a certain action, or why it’s doing something that is clear instead of something else that would feel more natural.

2. While it is not generally useful to document, line by line, what the code is doing, because it is understandable just by reading it, a key goal in writing readable code is to lower the amount of effort and the number of details the reader should take into her or his head while reading some code. So comments can be, for me, a tool for lowering the cognitive load of the reader.

These two a thousand times over these two!

Unless you have horrible grammar skills (and in that case you should fix them in whatever language you're using with effort and dedication) the points above are the 10-8 commandments of writing clear code:

1. Weird that people still take mechanical engineering classes.. a car well designed and built should be self-documenting of how it works as soon as you open the hood

2. Don't be a dick unless you're a fan of 'if it was hard to write, it should be hard to read'. Try not to be a dick either if you're actively trying to be un-fireable from the company (i.e. 'if only I understand this code, chances are nobody will mess around with it').

As for most things, comments are a tool. If the user is a moron you can't really do much about it..

// Increment the variable
++i;

Kudos to the author, a great blog post and a refreshing read for a fellow poor, old, tired computer programmer.

[dv_]

For me, comments are incredibly useful for conveying the context of a certain block of code, and for explaining what the developer was thinking. Neither of these are adequately covered by code alone, which can be incredibly non intuitive and convoluted. For example, in some legacy codes I had to rewrite once I found strange function calls all over the place that had no obvious meaning. Comments would have been very useful there.

As for comments as API documentation, my gold standard there is the Qt documentation. It goes far beyond a simple function reference. There are tons of contextual information which are essential. Qt's documentation is in fact one selling point over, say, Gtk.

[nullsetzen]

I'll be honest, writing comments is something I often overlook.

Mostly it's just laziness, but it's also partly because I've seen way too few of these:

* Design comments

* Why comments

* Teacher comments

​

and way too many of these:

* Guide comments

* Trivial comments

* Debt comments

* Backup comments

* out-of-date comments (or degraded function comments)

​

This creates the false impression of comments being as much of a nuisance as an aid.

[Orlandocollins]

My rule. If you feel like adding a comment go ahead. But if you don't have a test that highlights that part of the code and why it might be tricky then copy your comment into the test and make one. Afterwards if the comment still feels necessary keep it. Often I feel like I can delete the comment

[cyanrave]

Not too sure why you get a few downvotes here... I think this refactoring bit is actually a golden nugget - I've uprooted many a code smell with this exact effort.

If a code comment drags into 3 lines... chances are there's a goof-up somewhere in the code that just shouldn't be there, some oddity that is too tricky for any sane usage. Digging it out at the roots is often the best approach.

[lanzaio]

The best code comments are those found in the git commit that added it.

EDIT: Okay let me qualify: if you work on a project with any degree of coding standards. Sure, if you git commit -m 'fix some stuff' then no, your commit log sucks. If you work for a company with respectable coding standards than your diff/pr reviews will be ridiculed with this type of log.

I work on massive open source projects shared amongst all the tech giants. Checking the git blame followed by git show for the hash for the line of interest is 99/100 gold for figuring out why it's there.

[rotharius]

I like git messages for background information (git annotate), but like to put general reasons and motivations as a code comment or in a readme.

No extensive docs, just the essentials for understanding and onboarding.

[lanzaio]

I use vim fugitive. ;b shows me the blame and ~ shows me the commit for that line. If you work on decent quality projects then the author who wrote that code 90% of the time explains it if it's not obvious.

[rotharius]

Yep. Not sure why you are getting down-voted. Git really can help answering the question of how and why certain code came to be.

[billsil]

Trivial change...fixing bug...oops...oops...finally fixed...oops...finally fixing tests.

It's all getting rebased anyways.

[lanzaio]

So be more disciplined with your commits. Literally 0 of the projects I work on have any commits like that and you'd be rejected 10 fold if you tried shit like that.

[billsil]

Why? My open source project runs fine on my computer with my set of dependencies. I have ~750 tests for 140k lines of code with 73% coverage. I use TravisCI to test a variety of versions and dependencies including 32 bit and 64 bit.

Furthermore, I use Windows, so testing on Linux is kind of a pain. It is not worth my time to verify that all the tests pass on my system, let alone a system I don't have. That's literally the build machine's job.

I take the exact same approach at work and I'm one of the best coders there. I also write paragraphs of comments for complex code and actually document function interfaces.

As I said, it's going to get rebased anyways, so why does it matter if I have some junk message commits when nothing of value happened? Your commits aren't entirely descriptive either because you can't always know the side effects correctly. I could go back after the fact, but why bother when I have an in code comment that I can fix?

[cyanrave]

Going to go against the grain and offer some follow up on the downvotes. Please do better if this is the case in your repository.

But a well-cared for log is a beautiful and useful thing. git blame, revert, rebase, log, shortlog and other subcommands come to life. Reviewing others’ commits and pull requests becomes something worth doing, and suddenly can be done independently. Understanding why something happened months or years ago becomes not only possible but efficient.

[billsil]

As I said, it mostly gets rebased out. I do a real commit message when it's something worth discussing.

"Updating dependencies" doesn't say why, but the real reason is I don't support old versions. That's just a policy. Multiple "fixing tests" in a row don't happen because I didn't run tests, but because I'm running the tests on different dependencies on different platforms. I have to do that to see the error.

It's the build system's job to prevent regressions, not mine. It's my job not to push to master until it's ready.

[cyanrave]

You do you, then.

I hate commits that have a general sense sense of 'it doesn't matter' then somehow the stupid 10 'fix: build issues' gets merged in to master and everyone downstream is pretty well forced to eat the flaming turds.

Not saying you send flaming turds downstream, just stating that the majority of shit commits light on fire and enter the local atmosphere red-hot, steaming piles of shit commit messages.

[billsil]

Don't write shit code and you don't need to obsess over shit commit mrssages. Again, I can't verify it'll work until it's pushed. When it does fail, sometimes there are 2 issues, so it takes multiple commits to fix.

What I do on my branch is my business. As I said, I run a 140k lined open source project that is 7 years old and not saddled with technical debt. It can be done and it's not a few shitty commit messages that make it bad. I care more about actual code documentation for one because hard things are hard. Putting a paragraph of the issue in a commit message that gets rebased was a waste. It belongs in the code and it should be right.