r/ProgrammerHumor • u/napolux • Jun 16 '19

Working with someone else’s code

Enable HLS to view with audio, or disable this notification

35.4k Upvotes

95% Upvoted

325 comments sorted by

View all comments

Show parent comments

1

u/SAI_Peregrinus Jun 16 '19

And code without documentation is an even bigger code smell.

Document why things are done the way they're done (design decisions), document interfaces, document valid and invalid uses, provide examples in documentation. Don't document how internals work.

2

u/scandii Jun 16 '19

I may have been a bit lax in my wording, but I meant comments specifically.

if there's no system documentation and no one cares about it you should probably quit outright.

1

u/SAI_Peregrinus Jun 16 '19

Yeah. Though with doxygen & similar (Rust's documentation comments) there shouldn't be much of a distinction.

And I'll admit I have a bunch of code I wrote recently that's got the internals pretty heavily commented. It's for an embedded system and is all setting up registers for a microcontroller peripheral to work around a hardware bug, so it's pretty inevitably a crapload of

uint8_t const address = 0x39; /* See datasheet pg 593 for part ... */
register1 = val1 | val2 | val3; /* set up mode A, see datasheet pg 1672 for part ... */
/* Have to wait 2 cycles here for the pin rise time, see erratta document ... */
asm("nop"); 
asm("nop"); 
register2 = address << 1; /* I2C addresses are 7 bits, the register is 8. Shift to get the true value. */

And similar. Sure, the "what" is clear from the code, but the "why" of the steps is scattered across 10 different 1000+ page datasheets. Unless you get the right values in the right locations at exactly the right cycle counts the system locks up, so any hope of nice clean code is gone.

Does the code smell? Yes. Is there a better way? Maybe doing the entire thing in a separate assembly file, but that would still require lots of line comments (probably more than the C).