News for hackers. Stuff that matters.
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.