Self-documenting code?

Real   2 votes - 40 %
Not real   3 votes - 60 %
5 Total Votes
Self-documenting code by ucblockhead (4.00 / 3) #1 Sun Jul 23, 2017 at 01:49:19 AM EST
The last major piece of code I wrote was a python library, and I remember very clearly realizing that there were two approaches I could take.  The library handles a binary network protocol, and the various messages have a similar, though not identical, structure.

The first approach was to write it in straight python code.  This would have been clear as day to the reader, but would have required essentially new code for each message, nearly a cut-and-paste copy.

The second approach was to use internal data definitions and cool python reflection techniques so that supporting a new message required just adding an entry to a table and adding a new definition to another table.

The second approach is not trivial to understand without some brain work even if you know it well.  The approach that is more extendable and less buggy (less code == fewer bugs) is less readable. 

So of course I commented.  "If you want to do $blah, go do this in this table and add this to this other table" in addition to the "this is why I did it this way".
[ucblockhead is] useless and subhuman

Release crunch by Scrymarch (4.00 / 1) #2 Mon Jul 24, 2017 at 06:12:36 AM EST
I'm sure they're still around all over the place in industry, and I Wong claim we're immune, but we definitely seem to have them a lot less. Like once a year, if that. In a traditionally high pressure sort of domain. Maybe that makes me lucky, or maybe you'd do better at another place?

Iambic Web Certified

Way back by Herring (4.00 / 2) #4 Mon Jul 24, 2017 at 09:58:19 AM EST
when I was in a small startup, it often came down to cobbling together code, working stupid hours with little sleep to be ready for a client deadline. One observation that I made is that code written around 3:00am is frequently shit.

You can't inspire people with facts
- Small Gods

[ Parent ]
Er, won't claim, obviously by Scrymarch (4.00 / 1) #6 Tue Jul 25, 2017 at 08:13:07 AM EST

Iambic Web Certified

[ Parent ]
London nude sauna by hulver (4.00 / 1) #3 Mon Jul 24, 2017 at 06:53:45 AM EST
You're quite right. Horrifying and amusing in equal measures.

It does make me wonder what sort of expectations those guys have.
Cheese is not a hat. - clock

Germans and working hours by Herring (4.00 / 1) #5 Mon Jul 24, 2017 at 11:19:46 AM EST
Henning Wehn has a theory.

You can't inspire people with facts
- Small Gods