Re:Software engineering topics I changed my mind on
by lytefm on Sunday January 24, 2021 @05:21PM
(#25896772)
> I went from thinking "Comments are great!" to "Comments are terrible, and are liars, write self-documenting code" to "Comments are literally an opportunity for you to speak directly to the person coming after you, and explain in clear plain english WHY you made the choices you did, what tradeoffs you considered and dismissed, what compromises you made, and what external factors led to those decisions."
Wholeheartedly agree. Also, debugging logs for that same purpose can be great.
> Speak directly to your audience of future more junior engineers.
Often enough, that person might be yourself. I've been very grateful about my own comments in code areas that handled some obscure edge cases.
> That means every jump to another class and every jump to an interface with multiple implementations is a distraction.
Not to mention multiple layers of abstract base classes. I'd say „write your code such that you'll only ever need one IDE jump out of the current scope (and back in) to figure out what's going on“
Wholeheartedly agree. Also, debugging logs for that same purpose can be great.
> Speak directly to your audience of future more junior engineers.
Often enough, that person might be yourself. I've been very grateful about my own comments in code areas that handled some obscure edge cases.
> That means every jump to another class and every jump to an interface with multiple implementations is a distraction.
Not to mention multiple layers of abstract base classes. I'd say „write your code such that you'll only ever need one IDE jump out of the current scope (and back in) to figure out what's going on“