The Register Home Page

back to article The what, why, and how of pull requests and source comments

Veteran Microsoft engineer Raymond Chen has weighed in on the difference between a pull request description and comments embedded in the code. Both matter, but they serve very different purposes. As Chen noted on his The Old New Thing dev blog: "The PR description is a point-in-time statement, providing information that is …

  1. Pete 2 Silver badge

    Change control

    > pull requests

    Is that techy-speak for asking someone out on a date?

    > and source comments

    What the recipient of your request says about you afterwards on social media

    1. ComputerSays_noAbsolutelyNo Silver badge
      Trollface

      Re: Change control

      While your analogy is a good one, I fear that for many "asking someone out tona date" is even more theoretical than a theoretical discussion on the benefits of good code documentation.

      - Written without AI but with a healthy dose of sarcasm

      1. David 132 Silver badge

        Re: Change control

        "A date? How old do you think I am?"

        "Well all right, how about a prune."

        (With apologies to Saint Pterry)

  2. ttlanhil

    > but spaces now make more sense "because it always works and it's always consistent."

    If you think spaces for indentation is consistent, that means one of two things:

    1) you're not comparing against tabs for indentation, you're mixing tabs and spaces (which is *always* stupid - you get the downsides of both), or

    2) you think your indent size is appropriate for everyone else's screen, font size, eyes, etc...

    Tabs are more consistent - one tab is one indent level.

    Not the 1 vs 2 vs 3 vs 4 vs 8 spaces per indent level some people use (I've seen all of those).

    I use 4 spaces because that's most common, so it's what my editor is set to.

    Consistency and standardisation is one of the most important things.

    Except if I have to edit a Makefile, of course

    1. Bebu sa Ware Silver badge
      Windows

      Re: Except if I have to edit a Makefile

      /etc/syslog.conf was rather particular on tab in its earlier days I recall.

      I imagine configurable syntax directed "pretty printers" are a lot more common nowadays.

      Years ago I found the C utility indent which knows sod all about C syntax could re·render the most eccentric or plain loony formatting into something a little more mainstream.

      My petty hatred was for a C definition containing more (often a lot more) than one variable especially where objects, arrays and pointers were mixed.

      int i,j,*pi,counts['z'-'a'+1],(*sumfn)();

    2. Dan 55 Silver badge

      Something I do is align arguments to e.g. if, printf, arrays, or SQL over several lines as it aids readability, however lines with mixed tabs/spaces might not be shown correctly in editors which aren't defined to have a 4-space tab or you might find that someone else has had the same idea but some lines have been carelessly edited and include spaces between two tabs, when the spaces should only appear after the tabs.

      1. doublelayer Silver badge

        And that's where you want to use spaces only, no tabs. If you need indentation down to the character, use spaces so that shows the same. If you don't want that and are content with quantized levels, then you can use either but tabs make it easier for people to display to their taste. Using both just guarantees you get the bad parts of both.

        1. that one in the corner Silver badge

          > tabs make it easier for people to display to their taste.

          ONLY if everyone's tastes are all fully described using tabs.

          If any project is serious about people displaying code to their individual tastes, the ONLY method that will actually work (aside, that is, from making sure your team is only composed of tabbists and firing all heretics, which makes for an interesting report to HR) is to enforce the use of an automatic code formatter as a pre-commit hook and to (allow for) everyone to use their own selection of formatter and formatter settings as a post-checkour hook.

          That way, everyone literally sees things to their own tastes (or to their best ability to select formatter rules they are happy with - which then becomes purely a "them" problem and prevents them from being able to complain about anyone else's choices, which prevention is the sole purpose of this exercise) AND diffs between commits are always spared the pointless waste of showing 98% formatting changes hiding the 2% of actual useful change).

      2. Anonymous Coward
        Anonymous Coward

        editors which aren't defined to have a 4-space tab

        *lights torch* Tabs are *8* spaces....

        /coat

    3. that one in the corner Silver badge

      > If you think spaces for indentation is consistent, that means

      ONLY that the indentation, WHATEVER form it was following, is seen exactly the same way - i.e. consistently - by everyone and anyone who looks at the file, no matter which editor they use that time[1].

      You are confusing TFA's reference to consistency of display across users & editors to consistency of indentation within the work itself (or across related works).

      If, for some reason, an author has chosen to indent one line to column 3 and the one below to column 4[3] then using spaces allows this to be done, be done compactly (there is no useful purpose served by moving the columns even further across the page merely because the crude setting of tab stops would force that) and with total consistency no matter by who or by how it is viewed.

      BTW, you are also determined to discuss only indentation, aligning the LHS of a line. Traditionally, tabs were set for laying out tables more than just the (weird obsession of coders for) multiple levels of indentation. But even coders have tables to deal with. When writing out a static array of structs, say the contents of a state machine, I will arrange these as a table, with all the instances of the same member vertically aligned. Using spaces, not tabs, allows the columns to be arranged compactly and even with extra structure shown in a minimalist form: these three members are logically grouped and read together, so add one extra space before the first and one after the last of the group; those are now lightly emphasised but without excessively stretching out the lines of code.

      [1] Like, I would guess, most devs, I have multiple editors installed at the same time - for example, the one that I choose to use when writing code, the ine in the standalone debugger, the one in the VisualStudio install, the one in the *other* VS[2] that was present for maintaining some very old code, and, of coursek Notepad. Oh, and Nano and Vi and a bunch of others on the Linux box, some others on the FreeBSD boxes. The chances of all these editors being set up to interpret tabs the same way is precisely zero. And then some of them can interpret a comment at the start of the file as a command to set tab stops at certain positions; which command format differs across editors, of course (Emacs or Vim, or are you using EditorConfig notation?). Not forgetting that even commonly-used things like "tab every four spaces" is a painfully crude use of tab stops, compared to the humble typewriter which placed the stops at arbitrary positions across the page, allowing for simple creation of neatly arranged tables.

      [2] and the two VS editors don't even provide the same editor key bindings!

      [3] I would do something similar with, say, a long list of enum members: in this example, column 3 contains the opening brace, column 4 the first letter of the first member's name, immediately after the brace, then the other names align under column 4 - so their common prefix lines up and the space on the RHS of the line allows for comments of varying length

    4. Anonymous Coward
      Anonymous Coward

      Even working on fanfold greenbar paper, using tabs(8) will soon having you drinking more than I did when I was writing code in the late 1980s.and early 1990s.

    5. FirstTangoInParis Silver badge

      I’d love my shell scripts and config files to use tabs only. However vi appears to have other ideas. Tabs of 4 spaces auto generated to the next line, while keyboard tabs remain at 8 spaces. Drives me mad. Guess there’s a configuration option somewhere but haven’t looked yet.

  3. Bebu sa Ware Silver badge
    Facepalm

    "This was written by Alfred E Neuman …

    and I have no idea how the heck [whether] any of it works."

    Long before AI coding assistants, often just knowing what the code was supposed to do was a win and bonus was being able to determine whether it did (or not.)

    In those days it was often the system admin that was handed a tarball - often on some oddball tape format - of an application that was developed and claimed to run on a proprietary Unix system - of which no one had heard, or worse Eunice - with the poor sod asked to get it running on their sunos, irix, hpux, decosf, or aix etc systems.

    Generally after much spelunking through the code it becomes evident that a) the code didn't do what it was purported to do, b) was for a non-Unix and/or very obscure system, c) so broken could never have run in the first place. Sounds very much like any offerings from Microsoft does it not.

    Code comments are generally works of fiction worthy of a Nobel laureate than their accuracy.

    Tell young people today how vendors once arrived at so many variations of system v, bsd and posix signals - on one box - they just won't believe you.

    1. Dinanziame Silver badge
      Angel

      Ah, the five stages of debugging

      Denial: This works

      Anger: Why doesn't it work!?

      Bargaining: But it works on my machine!

      Depression: How did it ever work...?

      Acceptance: It never worked

  4. trevorde Silver badge

    Mythical 10x developer

    Many years ago, I worked with a bloke who was a 10x developer. He wrote huge swathes of code, masses of functionality, lots of bug fixes and ... no comments. He said his code was 'self documenting' but nobody could make head or tail of it. Management loved him but everyone else hated working with him.

    1. QuickLuck

      Re: Mythical 10x developer

      Current (hopefully soon to be "ex") employer has gone all in on 10X (corp policy is that x is capitalised and pronounced "ex" ... never "times"). And full throttle AI too. And the code quality has turned to shite. But it's quick shite. Except it's not. Every team just ticks their 10X then chucks the code over the fence to the next poor buggers. The one's holding it when the music stops get the blame

      Really can't wait for the pension to kick in and get out of the industry

      1. Dan 55 Silver badge

        Re: Mythical 10x developer

        Has your management (or any management) actually sat down and worked out with a calculator that developers are doing in 36.5 days what they previously did 365 days before daring to make the dubious claim that everyone is a 10x developer now? I doubt it.

        1. QuickLuck

          Re: Mythical 10x developer

          Calculator ? Calculator ? Oh, how quaint and sooo 20th century. It's all tokens in 2026. They used a gazillion tokens (which also made their AI usage stats look too)

      2. Anonymous Coward
        Anonymous Coward

        Re: Mythical 10x developer

        And if a huge increase in code produced then you now have a QA bottleneck.

        .. assuming you do QA properly that is (i.e. not go "AI" all the way down the rabbit hole and have "AI" QA) & don't use the approach of release and the end users can test it (waves at MS)

        Used to work at a place with a "10X" developer the management loved .. the other devs not so much.

        His coding style could be used unchanged in an obfuscated C competition.

        His ludicrous ideas were allowed - the worst offence about basic security was an API call, one of the parameters was a memory address, and it executed whatever was at that memory location. Yes, that would theoretically allow all sorts of nice functionality but FFS, this is the real world and it means you are creating a potential backdoor to system takeover (or at best just crashing things)*. Management were fine with it despite protests.

        Not sure if the API ever went live, it was certainly still in the unreleased code for the next big release of the product when I (& other devs I worked with) left as we wanted nothing to do with the fallout of it did go live (so now have no "sane" contacts left at that company to ask what happened)

        * Various safeguards were in place, but they were not (IMHO) anything like sufficient ("10X" claimed they were) and all irrelevant as such an API call was never needed anyway.

    2. bewilder

      Re: Mythical 10x developer

      I've worked in a lot of places where the TLDR mentality has completely taken over, where reviewers and senior engineers can't be bother to read anything detailed by way of documentation. The whole clean code movement indoctrinated a whole generation of devs to think that code is "self-documenting" by virtue of it's pure elegance. Absolute b*llcks.

      1. that one in the corner Silver badge

        Re: Mythical 10x developer

        > code is "self-documenting" by virtue of it's pure elegance.

        All MY code is beautifully elegant and self-documenting. It even makes up a complete Framework that provides all the scaffolding for a complete application, with --help options and everything, allowing one to concentrate on just the project logic.

        The fact is that I spent four solid days last week trying to remember precisely *how* I had arranged for it to elegantly scaffold together the self-documenting FSM interpreter[1] with the co-op scheduler[2] all to control the contents of some simple GUI widget[3] in a way that is going to be useful to me.

        All of this *is* self-documenting. Each individual logical section is gorgeously arranged and a treat to think about (he says, modestly). And turned out to be totally bloody useless when it came to remembering, all these years later, how these particular portions are intended to act together in harmony.

        The end result was: having read my own documentation, and my own self-documenting code, I wrote some MORE documentation, including more example code to illustrate, step by step, what Past Me considered obvious[4].

        My own code - and I know damn well that I'll be forever adding to, correcting, and RE-reading its documentation right up until the day I stop using it.

        For anyone who thinks their code is too elegant for documentation, the only response is to once again quote from bewilder:

        > Absolute b*llcks

        [1] it is definitely self-documenting, as a CLI option in the Framework will make it spew out all the details of every state transition; shame that wasn't the documentation I needed last week.

        [2] which *also* has a CLI option that'll enable a trace of what is waiting on what semaphore etc etc; neat, but once more, not what was needed then.

        [3] guess what, a CLI option exists that'll dump out the layout of widgets and show why that one has been moved too far over; hours f only that had been the data needed last week.

        [4] of course, now those bits are joined up as required and the widgets are widgeting, it really is all so obvious, only an idiot wouldn't have spotted immediately how it all hangs together!

  5. T. F. M. Reader Silver badge

    What, why, and how

    A few things that I was told in the beginning of my coding career (damn, I am old) and that I still tell youngsters.

    1. If what your code does is not clear from the code itself then your code sucks and it should be improved or re-written.

    2. Comments are for how to use the code, if it is not obvious. The meaning of function arguments cannot always be expressed succintly enough to fit the argument name. Preconditions, mentioned in TFA, are a good thing to comment, indeed ("this function assumes that this data structure is locked", etc.). Another good reason to make a comment is to explain the motivation behind choosing a particular data structure, a specific implementation, a specific choice between the options that were considered, etc. Complexity, performance, extensibility are among the things that may go into comments. This is why, but certainly related to how.

    3. Commit messages and PR (merge commit) comments should not explain what the code does - the "what" should be clear from the diff (cf. Item 1 above; if your diff is 15KLOC or is spread over 18 files in 7 directories you have a different problem - not for nothing so many reviews request splitting one PR into several). They should explain why the change is made or proposed. I wonder if vibe-bots can actually do that. I suspect that they summarize the changes - exactly what one should not put in commit messages - rather than explain the motivation. If anyone knows differently from own experience I'd like to know, because at this point I think commit messages are too important to delegate. And, with all the respect due to Raymond Chen, they are not political soundbytes to increase the chances the PR will be accepted quickly. They represent the evolution of the program and the motivation for writing this or that piece of it in the first place, and their temporal scope is a lot longer than one std::chrono::time_point,.

    1. doublelayer Silver badge

      Re: What, why, and how

      It depends on the system used. Many of them can write a PR summary that says why the code was contributed, sort of. It actually looks pretty good, except that like all LLM-generated things, it might not match the code it's attached to. It is often verbose, for example an LLM attempt to fix a bug will often include a lot of debugging details in the PR summary which are helpful when checking whether it hallucinated it but in a normal PR comment would be excessive. Feature additions tend not to include anything about the reason the team thought the feature was worth adding because the LLM has no basis for it. Admittedly, I frequently don't write that either because I'm lazy, the team already knows, and nobody is going to read it, but that's not something you want to emulate.

      This only applies to a harness that uses the LLM for coding; someone doing that manually with an LLM, whether by manually pasting things around or with a simpler IDE plugin, gets no PR summary unless they ask for it, and most ways of asking would not generate anything useful.

  6. Anonymous Coward
    Anonymous Coward

    Comments in code (good or bad) persist until someone edits the source code to remove / change those comments.

    Commit comments are potentially ephemeral. You may change source code control systems and so "start from scratch", or you may still use (e.g. git) but everything refactored and you start from a new repo to begin "clean" (for reasons unfathomable to me as that old history can be useful in answering the "why is this done this way" when original coders have moved on)

    May be security reasons to wipe all the repo history e.g. old codebase, had "secrets" in e.g. a config file, sensibly change code to have credentials, API keys etc not present in source code (injected when deployed or similar approach) - but have issue of old commits where the "secrets" still present so a nuking of commit history can be a safe approach security wise (yes, I know you could hack around with history to remove the "secrets", but that's slow & error prone so people often just nuke for safety / simplicity).

  7. Old fella
  8. David Hicklin Silver badge

    Comments in code

    As a hobbyist who plays with micro-controllers programmed using "C" I tend to write the what and how text of any function before I start writing the code.

    That way I can remember what I was planning or intending the function to do in the first place!

  9. RailwayGuy

    Comments are...not a dirty word?

    After far too many years of Bright Young Things sneering at me for putting comments in code (something that was practically beaten into me when I first cut my teeth in industry close to 30 years ago) I *still* religiously comment code. It's all too easy to adopt the 'good code documents itself' mindset but the truth is, you might know what it does now, you might know what it does next week. What about next year? Or in a decade? Or after a junior (or, worse, AI) has gotten their hands on it and 'fixed' it? I can barely remember what I had for breakfast some days, never mind some mind-bending feat of logic that I coded 20 years ago.

    I personally (and somewhat bizarrely) find comments to be soothing - they break the code up, divide it into 'areas', they add an aesthetic 'flow'. They also allow me an extra sanity check - if I'm trying to describe the code in a comment and it makes no sense then, err, is the code sensible? Is it overly complicated? Have I missed something or over-complicated something?

    Some people like to comment first and treat it as pseudo-code. Whatever works for you. But no, more and more graduates and 'geniuses' look down their nose at you if you comment code (including the 'genius' at one place I worked who loudly proclaimed that he didn't need to comment his code as, according to his uni lecturer, 'good code comments itself'. Then, less than a week later, had to ask me if I had any documentation for the code he was trying to debug as he couldn't understand it. That'd be the code that a previous dev hadn't bothered commenting).

    One of the mid-level devs who started with us recently commented that he found comments useful...but that *he'd* never add them in. Why? Why not pay-it-forward? Why not help your future self or whoever comes after you?

    So, as far as this dev is concerned, comments are not a dirty word

  10. donaldchavez319

    After the evolution of AI these things has changed a lot.

POST COMMENT House rules

Not a member of The Register? Create a new account here.

  • Enter your comment

  • Add an icon

Anonymous cowards cannot choose their icon