5 ms·
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 co
by adjkant 8y ago
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.
- zeroimpl 8y agoI 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.
- AstralStorm 8y agoAnd the 10% is unmaintained. Design patterns can tap you easily in bad designs. Usually the lost thing is performance, big way, or actual simplicity.
- AstralStorm 8y agoSince 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.
- nailer 8y agoHow long does it take you to write a sentence?
- james_s_tayler 8y agoTwice the time it takes you to write half a sentence.
- hexane360 8y agoHard disagree. You still need to think of the sentence to write the first half.
- james_s_tayler 8y agoBeg to differ. I consider the time taken to think and write as the aggregate time to write the sentence.
- nailer 8y agoYou've had to think of the design whether you write the sentence or not.
- james_s_tayler 8y agoInvoke gauge theory to set the floor from which we measure, so that the tautology always holds.
- nailer 8y agoI don't understand what this means.
- james_s_tayler 8y agoWell 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?