News for hackers. Stuff that matters.
Re:Please do not attempt to simplify this code by pdkl95 on Thursday December 27, 2018 @05:53PM (#18773373)
Ignoring the initial boilerplate (license, imports) and the request to preserve the verbose ("space shuttle") style, the first line is:

    // Design:
    //
    // [... 4 paragraphs of English prose
    //      explaining goals and intent... ]
That's exactly the type of comment that should be at the beginning of most files!
Re:Please do not attempt to simplify this code by jml7c5 on Thursday December 27, 2018 @06:33PM (#18773622)
As a novice programmer, I was absolutely stunned that this was not standard practice. A typical source file provides zero context, background on the subject, pointers to reference material/blog posts/books explaining the concepts, information on how it fits into the program's 'bigger picture', or (most importantly) the thought process that resulted in the file (i.e., why the choice was made to do _this_ rather than _that_, challenges faced, trade-offs, etc.).

It still baffles me. Every programmer has to start from scratch dealing with a new codebase, and it makes improving any non-trivial program impossible unless one is willing to spend hours of archaeological examination. To open-source developers: if you want to get people contributing to a project (and make everyone's effort much more enjoyable!), these sorts of comments are essential. Not to mention they'll save everyone boatloads of time; it's a shame that every programmer has to piece together knowledge from scratch, rather than being 'tutored' by their peers' comments.

Re:Please do not attempt to simplify this code by hibikir on Thursday December 27, 2018 @09:03PM (#18774350)
There's plenty of good reasons to not write 95% of code with big walls of explanation. The first is a matter of cost: Writing a good explanation around everything is very expensive to do at first. A whole lot of the custom code you find in random companies, from the shiny SV startup to the old enterprise, is unimportant, cobbled together pieces. We have no idea of whether we are writing code that will be thrown away in a week, a month, a year or whether it will last two decades. Context can change fast enough that the comments become worse than useless, as the terminology might have changed, or had been misguided in the first place, turning the long comments into outright unintended deception. This gets even worse as we do not evaluate all the comments in all the files whenever there's a code change: It's crazy how a large comment block in one place can become harmful after it's forgotten, and someone else makes a correct, business critical change in another file. No matter where I am working, it's rare for me to not find multiple examples every year where the code and the comments provide very different impressions of what is going on, and it's the code that is accurate.

This is not to say that there aren't reasons to write large comment blocks, or architecture documents, but that they are often better written not while the system is being first built, but later, in a maintenance cycle, when someone already had wished for the comments, and has regained the knowledge the hard way. By then, it's clear which part of the system are dangerous, suspicious and unclear. Where there's more need for high quality error handling, and where thousands of lines of error handling never get hit, because the failing case that was originally considered doesn't really happen in this dimension anymore.

Writing code so that someone, even a future you, can pick it back up and improve it when it's needed, while still delivering the code at a good pace is a kind of skill that many just don't learn, either because they are always in greenfield teams that never pay for their mistakes, or have an approach to maintenance that involves not becoming intimate familiar with a system, and instead either hack or rewrite.

But nobody looks great in a resume by saying that they are a specialist in software maintenance.

Re:Please do not attempt to simplify this code by TeMPOraL on Friday December 28, 2018 @01:30AM (#18775183)
> This is not to say that there aren't reasons to write large comment blocks, or architecture documents, but that they are often better written not while the system is being first built, but later, in a maintenance cycle, when someone already had wished for the comments, and has regained the knowledge the hard way.

I don't think the "Lean Manufacturing" approach works here. By the time someone "pulls" you for a comment, you've already lost the most important knowledge that should go into the comments - why the code is the way it is. Maybe you'll recall it when asked, hopefully not missing anything crucial. Meanwhile, comments are extremely cheap to write as you're writing the code, and even before you're writing the code (you did spend the time thinking about what you'll write, and aren't just "coding from the hip", right?).

Re:Please do not attempt to simplify this code by vthriller on Friday December 28, 2018 @07:36AM (#18776401)
Commit logs are also cheap to write, and it's easier for people to realize that whatever you read in "$vcs log" or "$vcs blame" might be severely outdated.
Re:Please do not attempt to simplify this code by garmaine on Friday December 28, 2018 @04:31AM (#18775779)
I down voted because although I think what you are saying is common parlance, it is really, really bad advice and mixes up causality. Projects which both do their job and are this well documented attract developers, both to maintain and reuse. Look, for example, at everything done by Armin Ronacher, or at SQLite.

And writing documentation only seems like a waste of time to the developer who just finished writing the code. It wastes their time. But spending time now to write good documentation saves the organization as a whole much more of other developer's time in the long run. It's a smart investment to make, even when the collateral damage is time wasted documenting code that really is thrown out.

(But, if you actually document the code well you'll find out that you throw things out much less often.)

Re:Please do not attempt to simplify this code by ozim on Friday December 28, 2018 @07:48AM (#18776438)
I don't think downvoting is good way for showing disagreement.

I disagree with what you wrote. It does not waste developers time, it wastes money of business owners. Developers are usually paid for their time even if they are reading HN instead of working.

Now question is to people who pay money if they want to pay for "something in the future maybe will be useful". They will say hell no! They want time to market to be as short as possible and as much of end user value delivered.

Now you take example of SQLite or Armin Ronacher those are exceptions. There is a lot more software that is not anything done by Armin and is not SQLite.

Re:Please do not attempt to simplify this code by bmh100 on Friday December 28, 2018 @12:48PM (#18778219)
This is why the business is usually not asked to make engineering decisions. Things like backups, disaster recovery, and redundancy could all be described as "something in the future maybe will be useful".
Re:Please do not attempt to simplify this code by garmaine on Friday December 28, 2018 @08:58AM (#18776701)
Bad advice should be kept highly visible.
Re:Please do not attempt to simplify this code by garmaine on Friday December 28, 2018 @09:14PM (#18781300)
Er, "should not".
Re:Please do not attempt to simplify this code by dwild on Friday December 28, 2018 @11:00AM (#18777473)
> We have no idea of whether we are writing code that will be thrown away in a week, a month, a year or whether it will last two decades.

Sometime also a code is meant to be temporary but is later deems to useful not to be used but no resource is allocated to is maintenance (in this case we could say refactoring). It's the case of many internal tools.

I remember when I did my first internship, I was in the configuration management team and I was responsible for doing the smoke test. I made some tools for myself to speedup the process and once my manager saw how useful they were, he was interested of giving them to the QA department. I refused because it broke every few builds and I knew after my internship I wouldn't be there to maintains them and it would just create more problems. There's so many instance where it wouldn't break so often or that person wasn't considering he would no longer be there to maintains it or won't have the time.

Re:Please do not attempt to simplify this code by tracker1 on Friday December 28, 2018 @06:06AM (#18776119)
I think that the example given is a great example of code that will be around for a while... as mentioned, the logic was in 3 files and needed heavy refactoring. That refactoring has happened and the logic is well documented. In this case it isn't going anywhere.

That said, I mostly agree... I tend to favor a discoverable code base, where the directory structure is organized over features... for example a given feature may have a few controls, some actions, state logic, api client for foreign system, etc... any of the above. I organize by the feature, not the type of files/components of those features.

I tend to favor using abstractions only when they are simple enough, or make the related code much more simplified and understandable. The exception to this is needed complexity, such as an enterprise product that needs to support being deployed on oracle, sql server, etc.

Simple, replaceable code is often better. That said, when you have a broadly used produce and a piece of functionality that is well used, moderately complex and unlikely to dramatically change, this level of detail isn't a bad thing.

Re:Please do not attempt to simplify this code by db48x on Thursday December 27, 2018 @10:59PM (#18774795)
Always say Software Archaeology instead; it sounds better.
Re:Please do not attempt to simplify this code by pas on Friday December 28, 2018 @06:58AM (#18776267)
I vehemently disagree.

Code without specification is a maintenance nightmare, a pure liability, a ticking time bomb.

And sure, unless you're creating the control system of a nuclear reactor/warhead you don't have to go full Coq and CMMI5 and "high assurance" and whatnot, but spilling a few sentences as a minimal kind of pseudocode before writing what you want (a function, a class, a method, change the build system, refactor a big ball of if-s) is almost ideal. It helps you double check yourself, and it helps reviewers too. (Throwing there links to some issue tracker is also nice, but just the links are not very helpful.)

If you have to write docs later, it's hacking (reverse engineering), not engineering.

Re:Please do not attempt to simplify this code by dwild on Friday December 28, 2018 @11:07AM (#18777524)
Personally I consider that if the code don't speak for itself, then it's most probably bad code, if it's not, add a comments explaining why it's not.

> spilling a few sentences as a minimal kind of pseudocode before writing what you want

Isn't it simply repeating the code you'll write? Which in the end, will be just as bad as the code alone or will lose time of the one that will read it afterward.

Sure it's hard to write good code, sure it's not always obvious what's bad code, but that's a big reason why the review process is there. It's not only to catch mistakes, it's also to see if someone else can understands what the code meant, the context, the decisions, etc... Sadly many just go quickly over it and just check for obvious mistakes.

Re:Please do not attempt to simplify this code by pas on Saturday December 29, 2018 @06:38AM (#18783182)
Code cannot explain the engineering constraints, the business orientation, the goals. Ie. it must work in IE10 so we use this or that.
Re:Please do not attempt to simplify this code by qlk1123 on Thursday December 27, 2018 @07:37PM (#18773932)
> 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.

Re:Please do not attempt to simplify this code by TeMPOraL on Friday December 28, 2018 @01:34AM (#18775197)
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.

Re:Please do not attempt to simplify this code by jnurmine on Friday December 28, 2018 @03:00AM (#18775411)
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.

Re:Please do not attempt to simplify this code by notacoward on Friday December 28, 2018 @10:47AM (#18777374)
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.

Re:Please do not attempt to simplify this code by dwild on Friday December 28, 2018 @11:20AM (#18777632)
> 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.

Re:Please do not attempt to simplify this code by notacoward on Friday December 28, 2018 @11:42AM (#18777780)
> If your "why" doesn't contains this, I have an hard time understanding why you want it in the first place.

The "why" doesn't need to include every minor style nit (all the way down to variable naming) that came up during the review. It doesn't need to include every "I would have done it this way instead" comment which was in neither the original nor final version. That's noise, not signal.

> Personally every time I only needed a tiny bits more context

Lucky you. For much of the code I have read or written, that was not the case. In general it tends to be less and less the case as code climbs up the complexity/innovation scale.

> I'd rather die than lose time over something I consider won't save time in the long term.

Is that an unavoidable issue with the medium, or more of a reflection of how some people are bad at writing? I've whipped out a spec for a medium-complexity feature or component in under an hour, and been thanked for it five years later. Many times. If you've never had that experience, then I can only say I hope you'll be able to some day.

> when we do, the ticket information is enough and if it's not

Again, lucky you. Others have a different experience.

Re:Please do not attempt to simplify this code by ptyyy on Friday December 28, 2018 @02:30PM (#18778859)
Seen from our offshore with regularity:

> Minor fix

> Showing 6 files with 171 additions and 203 deletions

Re:Please do not attempt to simplify this code by nerflad on Thursday December 27, 2018 @08:05PM (#18774079)
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.
Re:Please do not attempt to simplify this code by busterarm on Thursday December 27, 2018 @08:07PM (#18774084)
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.
Re:Please do not attempt to simplify this code by garmaine on Friday December 28, 2018 @04:35AM (#18775790)
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.

Re:Please do not attempt to simplify this code by Cthulhu_ on Friday December 28, 2018 @03:44AM (#18775600)
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)

Re:Please do not attempt to simplify this code by tapland on Friday December 28, 2018 @09:02AM (#18776727)
> unless one is willing to spend hours of archaeological examination

Currently the only person in-office over Christmas on my first software dev job. Debugging a 50k LOC COBOL beast that digs into three other beast programs and ends up in a final 20k LOC uncommented piece where things are supposed to happen and be returned back.

Nothing is commented, the programs are huge and one can only debug one program at a time, requiring me to submit untested changes in one of them to the shared dev environment since I'm making changes in two, before debugging the other program.

If it just said somewhere what half of the stuff is I would save an insane amount of time getting to know the system.

Re:Please do not attempt to simplify this code by vonseel on Friday December 28, 2018 @10:41AM (#18777337)

  my first software dev job. Debugging a 50k LOC COBOL beast
We found the real MVP. tapland, what were you thinking when taking this job!?
Re:Please do not attempt to simplify this code by tapland on Sunday December 30, 2018 @10:59AM (#18789733)
Heard about COBOL for ages, always been into retro computing and setting up z/OS on the Hercules emulator at home I was offered COBOL-training from a company and two years of guaranteed employment (with pay even if they decide I'm not needed) to join a team that force-retired 40% of their developers this year.

I have no real previous development experience, only some Java and Python, since I chose an industrial engineering program at uni, and I got the offer the semester before my CS-classes (my chosen specialization) started.

Changed my university classes to equivalent distance-classes and took six months of school to get into training and a job.

Re:Please do not attempt to simplify this code by adjkant on Thursday December 27, 2018 @06:48PM (#18773697)
I think your desire is right, but think about this every time you create a file, and how much slower your work would be. The question then becomes: "how much commenting exactly is needed before this becomes more time than the technical debt it creates?

I think this type of summary should not be per source file but per package/folder/module/project. A high-level developer overview with sufficient depth will also help stop repetition of philosophy in subsequent files.

In this case, I do agree with its existence though because of both the length and complexity of the file. For many files, neither are the case.

Re:Please do not attempt to simplify this code by zeroimpl on Thursday December 27, 2018 @07:53PM (#18774009)
I think this commenting only makes sense if the design is atypical. Probably 90% of the code I write is following design patterns already used throughout the code base.
Re:Please do not attempt to simplify this code by AstralStorm on Friday December 28, 2018 @09:26AM (#18776851)
Since comnenter announce does not understand what I meant, it does not matter if design is typical. Functionality still has to be described, so the pattern itself buys you nothing on its own. Then the overarching idea and reasoning also has to be described to make it easier for everybody else to understand.

I've met more than one codebase which tried to use a big hammer pattern to open doors. Heavy indirection to do simple things because of design choices, usually caused by a forced framework - instead of easily factorizable simplicity. Patterns should be emergent not forced. Or more specifically, the choice of appropriate pattern should be based on the problem being solved, rarely one pattern can cleanly solve all problems.

Similarity is very seductive but end result is often complex and hard to reason about when followed religiously.

Re:Please do not attempt to simplify this code by AstralStorm on Friday December 28, 2018 @04:47AM (#18775852)
And the 10% is unmaintained.

Design patterns can tap you easily in bad designs. Usually the lost thing is performance, big way, or actual simplicity.

Re:Please do not attempt to simplify this code by nailer on Thursday December 27, 2018 @08:45PM (#18774269)
How long does it take you to write a sentence?
Re:Please do not attempt to simplify this code by TeMPOraL on Friday December 28, 2018 @01:37AM (#18775207)
Sometimes a lot. Because what I'm really doing in my head then is the design work (writing a sentence actually helps with that) - the work that's actually necessary to write the code well.

When I read something saying "writing thoughtful comments is too much work" I really read this as "thinking about the code you write is too much work, it's better to write whatever crap that first comes to mind".

Re:Please do not attempt to simplify this code by james_s_tayler on Thursday December 27, 2018 @09:22PM (#18774410)
Twice the time it takes you to write half a sentence.
Re:Please do not attempt to simplify this code by hexane360 on Friday December 28, 2018 @01:10AM (#18775137)
Hard disagree. You still need to think of the sentence to write the first half.
Re:Please do not attempt to simplify this code by james_s_tayler on Friday December 28, 2018 @03:36AM (#18775562)
Beg to differ. I consider the time taken to think and write as the aggregate time to write the sentence.
Re:Please do not attempt to simplify this code by nailer on Friday December 28, 2018 @04:46AM (#18775848)
You've had to think of the design whether you write the sentence or not.
Re:Please do not attempt to simplify this code by james_s_tayler on Friday December 28, 2018 @08:43AM (#18776630)
Invoke gauge theory to set the floor from which we measure, so that the tautology always holds.
Re:Please do not attempt to simplify this code by nailer on Friday December 28, 2018 @05:05PM (#18779833)
I don't understand what this means.
Re:Please do not attempt to simplify this code by james_s_tayler on Friday December 28, 2018 @07:46PM (#18780815)
Well people keep picking arbitrary starting points in the coordinate system. I'm saying for any arbitrarily picked starting point in the coordinate system, the time taken is always twice that of getting from the arbitrarily picked starting point to the halfway mark.

A tautology is a tautology.

How long is a piece of string?

Re:Please do not attempt to simplify this code by nailer on Saturday December 29, 2018 @04:25AM (#18782802)
You're not a very effective communicator.
Re:Please do not attempt to simplify this code by james_s_tayler on Saturday December 29, 2018 @07:40AM (#18783332)
I'm glad we're on the same page.
Re:Please do not attempt to simplify this code by zachberger on Friday December 28, 2018 @01:25AM (#18775167)
You may want to checkout the python standard library files. heapq.py, for example, has some amazing documentation in it:

https://svn.python.org/projects/python/trunk/Lib/heapq.py

Re:Please do not attempt to simplify this code by matte_black on Thursday December 27, 2018 @10:23PM (#18774674)
The information you are talking about is called documentation and it should exist outside of actual code files.

If you need to read comments to understand code, you don’t know how to read code. Comments can lie, only code is the source of truth, once you gain experience you won’t bother with comments.

Re:Please do not attempt to simplify this code by jniedrauer on Thursday December 27, 2018 @10:32PM (#18774708)
> The information you are talking about is called documentation and it should exist outside of actual code files.

The file in the OP is Go. In Go, you are encouraged to write documentation and code in one place[0]. The end result is very nice, auto-generated, human readable documentation[1] which is tightly coupled to the code it documents.

[0]: https://golang.org/src/net/http/doc.go

[1]: https://golang.org/pkg/net/http/

Re:Please do not attempt to simplify this code by fogetti on Friday December 28, 2018 @12:00AM (#18774979)
Sure, and then the next day the whole thing is just a long boring text which has no correlation to reality because the business rule changed and the developer next to you refactored the code.
Re:Please do not attempt to simplify this code by TeMPOraL on Friday December 28, 2018 @01:40AM (#18775211)
If the developer next to you refactored the code without refactoring the comments, they did a shit job. Period. They need to be told to go back and fix it.
Re:Please do not attempt to simplify this code by fogetti on Friday December 28, 2018 @01:57AM (#18775250)
Or maybe the original developer who wrote the code which was so poorly written that it needed 4 paragraphs of explanation did a shitty job. Period. They need to be told to go back and fix it. You see! You argument works both ways, yay!
Re:Please do not attempt to simplify this code by TeMPOraL on Friday December 28, 2018 @02:03AM (#18775267)
Of course it does.

If the comments are completely redundant with the code, they're bad. But you can't express as code why the some code is the way it is, and why it does what it does. After you tried to express in code every important information that's expressible as code, whatever important information remains must go into comments.

Re:Please do not attempt to simplify this code by fogetti on Friday December 28, 2018 @02:12AM (#18775291)
False dichotomy. You are trying to make this black or white while there are many more options beside comments. There are even obvious ones beside comments.
Re:Please do not attempt to simplify this code by AstralStorm on Friday December 28, 2018 @04:48AM (#18775860)
You could. It is called an automated theorem prover, with the cheap limited version called constraint based programming. Sadly very unavailable for most programming languages.

Sometimes writing the proof of why it should be like this is tricky, especially when complexity or performance is involved. (But then the tests are hard too.)

Linters are essentially constraint systems for code, but not for the program.

Re:Please do not attempt to simplify this code by TeMPOraL on Friday December 28, 2018 @05:43AM (#18776048)
Theorem provers can still only talk about what the code does and whether or not it does it correctly. Specifying why the code is there is an AI-complete problem. Hence, comments.
Re:Please do not attempt to simplify this code by flowardnut on Friday December 28, 2018 @05:50PM (#18780133)
This is one reason I like cucumber -- capture features in plain english, and also write tests to verify your plain english features actually work.

It's an odd feeling, having the best of both worlds.

Re:Please do not attempt to simplify this code by ElijahLynn on Thursday December 27, 2018 @07:50PM (#18773992)
One thing that I wish Linux kernel code had. Maybe it does but the few times I have found myself reading Linux code I go to the top and there is zero context in the comments, just a bunch of licensing information.
Re:Please do not attempt to simplify this code by dfox on Thursday December 27, 2018 @09:23PM (#18774418)
There are few linux drivers for particularly buggy hardware that are written in this style. Although OTOH what I think of is hme.ko, where the comments are more on the hillariously funny side than descriptive.
Re:Please do not attempt to simplify this code by isp on Friday December 28, 2018 @06:34AM (#18776194)
I wasn't familiar with hme.ko comments, so looked it up.

https://github.com/torvalds/linux/blob/master/drivers/net/et...

Re:Please do not attempt to simplify this code by AstralStorm on Friday December 28, 2018 @09:55AM (#18777026)
The kernel code is nowhere near ideal nor "space-shuttle" code. It has a ton of single use functions which is essentially the opposite.

Magic numbers and timing without explanation why. Rarely used technical descriptions such as "Lance mode". Tons of unchecked assertions on lock when kernel provides a lockdep check for this. Custom logging macros. Flies in the face of kernel "goto error" error handling convention in a few places. XXX with obvious bugs mentioned, unfixed.

And more...

Splitting it into more files wouldn't help at all.

Re:Please do not attempt to simplify this code by TeMPOraL on Thursday December 27, 2018 @05:56PM (#18773393)
Strongly agreed. Wrt. comments, the more I read this file, the more I see it as a reference of how good code should look like.
Re:Please do not attempt to simplify this code by everybodyknows on Thursday December 27, 2018 @11:58PM (#18774972)
Hews closely to the advice offered by Go's creators:

https://golang.org/doc/effective_go.html#commentary

Re:Please do not attempt to simplify this code by sridca on Thursday December 27, 2018 @07:47PM (#18773978)
Yea, but watch how soon it becomes outdated as the file changes.
Re:Please do not attempt to simplify this code by YorkianTones on Thursday December 27, 2018 @08:47PM (#18774285)
This. Documentation (comment blocks in code, as well as all other forms of documentation) tends to become outdated because it is not maintained in sync with every code change.

Solution: write clear, simple, modular code that is self-documenting and does not need extensive commenting.

Re:Please do not attempt to simplify this code by TeMPOraL on Friday December 28, 2018 @01:45AM (#18775225)
How soon? I've rarely seen it happen in a meaningful way (i.e. other than someone using automated refactoring on some name, and breaking some comment reference that wasn't written in a way the autorefactor tool could read). When it happens and you see it, you should fix it like any other bug.

Key trick is writing comments as close as possible to the code they affect. Then it's hard to miss affected comments if one's not doing a shoddy job.

Re:Please do not attempt to simplify this code by dllthomas on Friday December 28, 2018 @01:27PM (#18778485)
> Key trick is writing comments as close as possible to the code they affect. Then it's hard to miss affected comments if one's not doing a shoddy job.

That also helps it show up in a PR so it may be caught in code review. Even so, IME comments get missed enough that over time I can't be as confident as we'd like that they match the code.

I think it's also worth calling out that this key trick is not being applied in the recommendation up-thread, which asks for a block comment at the top of the module.

Re:Please do not attempt to simplify this code by tome on Friday December 28, 2018 @05:41AM (#18776040)
I've done it frequently myself when I've changed a line that I originally wrote myself in a way that invalidates a comment written directly above.
Re:Please do not attempt to simplify this code by atulatul on Friday December 28, 2018 @12:01AM (#18774982)
Overall liked the original post. But also liked what you said.

But here are a couple of Martin Fowler quotes (from his Refactoring book) I tend to follow:

“A heuristic we follow is that whenever we feel the need to comment something, we write a method instead.”

“Whenever I have to think to understand what the code is doing, I ask myself if I can refactor the code to make that understanding more immediately apparent.”

https://www.goodreads.com/author/quotes/25215.Martin_Fowler

Re:Please do not attempt to simplify this code by garmaine on Friday December 28, 2018 @04:37AM (#18775800)
Reject pull requests that don't update the documentation (and tests).