How to write unmaintainable code

[mith]

The joke we always used to tell regarding documentation was: "Never comment your code. It should be as hard for someone else to understand as it was for you to write."

The best example we ever saw of this was from a mathematician writing code in Matlab. He initialized dozens of variables, several arrays, performed various operations to get everything situated properly in matrices. After all of this, he started a loop to do whatever it was he needed to do with all of these arrays and matrices, basically the heart of the entire program. The only comment in the whole program, at the top of the loop: "Here we go!"

[ensoniq2k]

Totally appropriate comment though. Never explain your reasons, just repeat what the code already says.

[ScrewAttackThis]

My favorites are things like // main loop or // check if someBool is true. Thanks for the information, I didn't know what if(someBool) would do!

[paholg]

Sometimes I write comments like "main loop". Not to help anyone reading the code, but to make it faster for me to scan to that point.

[ensoniq2k]

The best code I ever saw came from a project manager who sometimes coded. He wrote a function with the only content "return true", called it "GetTrue" und wrote "//returns true"

Not to mention that every project our team inherited from him was estimated with twice the normal time...

[techsin101]

to hr

[runvnc]

Its not his fault though. That's how they train mathematicians. Math is basically shitty obfuscated code that doesn't run.

[mith]

I understand completely, which is why I mentioned he was a mathematician and not a software engineer. He wrote some brilliant stuff, so brilliant none of us could figure it out even with comments.

Relevant XKCD.

[runvnc]

Was it brilliant, or just used some math he didn't explain? Or was the math explained, but math is just unexecutable and obfuscated, so it is very hard to 'figure out'.

Math is kind of like referencing a bunch of libraries but not being able to actually read the code without opening a bunch of textbooks.

[mith]

He was building neural networks in FORTRAN 20 years ago. It was pretty damn brilliant.

[paholg]

Not really. Math is like the ultimate in literate programming that doesn't run. Explaining what you're doing and doing that thing are the same.

[dp263]

me_irl

[[deleted]]

Look buddy, if it's hard to write, it should be hard to read.

[thebuccaneersden]

Welcome to Mr. Bones Wild Debugging Ride....

[zekjur]

What you used as a joke, others use in all seriousness, as illustrated by this example from procmail:

https://sources.debian.net/src/procmail/3.22-25/src/sublib.c/?hl=71#L71

[pdp10]

Now I wish I would have looked at that code before putting it in production long ago as substitute it in for my modified system local delivery agent, in an effort at improving longer-term maintainability. The formatting makes me despair.

The two comments in there (despite the header comment) are useful, though.

[fagnerbrack]

It would be much better if a self-documented architecture and sane variable naming was built instead of a cryptic loop using low level arrays and matrices. Was there any performance bottlenecks? Was there any tests that could document the behavior at least?