When I finished my studies, I was looking for a job and had an interview at a smallish company.

Boss: can you do C?
Me: yes, I have already done some stuff in C.
Boss: I mean, are you really good in C?
Me, growing suspicious: well yes I already have been using it - but anyway, there's also the project documentation for looking up, right?
Boss: uhm, the code IS the documentation.

I envisioned myself being drowned in undocumented spaghetti code and wasn't really keen on that job anymore, but my following question pretty much ended the interview:

Me: oh, I see. Do you have any roadmap for getting your development to a more professional base?

His looks, priceless! He was just shocked when he realised that he had failed my interview, and that I was a fresher made it even harder to digest for him.

I like that. You did put it right in the hole !

Salute..

I'm using this! Priceless! 😂😂

This is so beautiful, kudos for the priceless sentence!

I am on the side of your boss! Good code doesn't need comments. (depending on the type of project, you need docs though)

@gnulinuxer4fun luckily, he didn't become my boss, and good code does need comments. Not on the what, that should be self-explanatory, but why. Everytime I have to seriously think, these thoughts have to go into a comment. Because, if it were trivial, I wouldn't have been thinking in the first place, right?

@Fast-Nop they go into good variable and function names. In my eyes, uses of comments are a personal failure (exceptions to be made).

1) comments can get deprecated or lie

2) comments are usually a justification for not coding cleanly

3) comments are clutter which is often overread

4) commenting takes time

5) commenting might cause trouble with some software that processes code (unlikely, though. don't count that as an argument :P)

@gnulinuxer4fun I think it's telling that you didn't address the what/why difference because names just don't describe the why factor.

However, the why becomes crucial when you add new features because you have to make sure that they work with the rest, and then it's helpful to know why the rest is like it is. That's why lack of meaningful comments creates maintenance issues.

Btw., other project documentation (which was missing in that company) can get outdated, too. I guess they followed your logic and just left it out.

@Fast-Nop if you need a "why" in your code, you work with monkeys who have no idea on how to code. Sure, if there are 10 ways of implementing things but you chose the inferior one for some reason, add a polite comment. but how often does that happen? Do I need to add a "why" to my choice of the algorithm? No: I chose the fastest one. Also, everything is (should be) encapsulated in unit tests which give MORE than enough context to everything.

If you disagree, that's fine. But then, we should stop the debate. Both of us have laid down our arguments and continuing the argument would just be unproductive

@gnulinuxer4fun fuck I sound way angrier than I am :sweat_smile:

@gnulinuxer4fun you look at a very small scale. Sometimes you have to work with legacy tools, with external tools or its just a requirement from the business to do something this way or another.
In my app, there are things that seem useless and bizarre, but there are some external tools using our code - and you just can't rework it.
Thing that annoys me - search term is passed as part of the path in url not as querystring. That causes tons of problems with special characters, but I can't force other tools to stop using it. Its difficult to force other PM-s that in few next releases we need to drop the scheme. And even harder when the PM has no idea of how HTTP works.

@gnulinuxer4fun recent counter-example even for an algorithm: I didn't choose quite the fastest one and went with Shellsort instead of Quicksort. WHY? Because it's on an embedded system and Shellsort doesn't need variable stack space.

Then some rather hacky way of doing things because I need to work around a PCB layout bug, and the normal way of proceeding would create an occasional HW/SW race condition - which I found out after a solid two weeks of debugging.

Then some special stuff that doesn't make sense until you know the physical constraints that happen outside of the system in its intended usage scenario, but even then only in a certain temperature range.

Unit tests wouldn't work here, and even if they did, they wouldn't tell the next dev on the project what the point of these things really is. It would be a "don't touch it, or things mysteriously break" codebase.

@mt3o Sure - if the company requires it - why not. But why make it a requirement for the company to produce bad code?

- those guys don't comment their code, thus it's a bad company => that doesn't work, IMHO

But, getting back to the documentation, lack of it can be expressed as lack of comments in the code, but also by lack of official documents with specifications on architecture of system and code, or even tickets ordering certain functionalities. Just emails, or even lack of them :)

@gnulinuxer4fun agreed. The general need for comments are for libraries you create for others to install, such as APIs or utility libraries. Other than that, clean, good code should really be self-documenting via exceptional naming.

Comments becoming lies is way too easy and way too common. Source control is where comments and why's should be ironed out, and each commit should reference the issue ticket where this documentation resides.

Don't just take our word for it though, Robert Martin (Uncle Bob) makes all the arguments necessary as to why code should be self-documenting and that comments within code tend to end up being excuses and/or lies (outside of the exceptions I mentioned above).

https://cleancoders.com/videos

https://amazon.com/Clean-Code-Handb...

@duckWit someone's got my back <3

@Fast-Nop sure, in that case, if you have NO possibility of mentioning your decision outside of the code, add a comment. 1 line, quickly describing your issue, directly between the function head and the braces, that way it doesn't get lost elsewhere

template<class T, int n>

T sort (std::array<T, n> &input)

// shellsort is faster, because our system has limited variable stack space

{

}

In a good codebase, such comments will happen maybe twice in a 400 LoC file.

But again: if your code mates have an idea of the embedded system, they will know why you chose shell sort over quicksort. And if your mates don't, teach them. As a professional, it's your responsibility to make the entire team move forward.

@gnulinuxer4fun

//it is like it is because PM won't give us budget to rework this legacy garbage

// we use X, sorry, we know its illogical, but it was in the business requirements
// // requirements were given by email and are not stored in any wiki or ticket system

:D

I'm happy as hug that I don't have to worry about budgeting, scheduling nor doing only stuff that is described in the tickets. Is awesome to be able to do refactoring without asking for permission of any sort :D

@mt3o asking for permission before refactoring?

@gnulinuxer4fun as soon as we're talking about certified systems, you can't just change the code, and if it's just because a delta test verification run is out of question.

@gnulinuxer4fun if you are doing certain ticket, you can't do whatever you want. Your code should be taken under code review, you can be asked to correct it, can be rejected, you can be asked to justify your decisions.
For what I see, in my team, external coders don't have the liberty to do whatever they want. They need validated ticket and have time assigned for it. Introducing changes, refactoring, is difficult because its never ticketed. I force some things by making business aware that some changes have to be done because X Y and Z, and it works sometimes, sometimes not. It didn't with the path param vs query string issue. I was unable to put into the PMs mind that keeping pathparam is a bad practice and replacing just few explicitly named symbols won't solve the problem. Luckily, I don't have to work with that PM and that piece of code is not my problem anymore.

But on other occasions, I do those refactoring changes without asking anyone for permission, doing related, or unrelated stuff. That's a bad practice when applied in larger teams. My team consists of 1 developer, 1 guy supposed to be a dev who left, and few external coders. And few other people working on deeper layers beyond my app.

@gnulinuxer4fun @duckWit @mt3o @Fast-Nop

I have come to end this nice debate. Comments are often used to explain the train of thought the coder goes through, which is kinda wrong. We don't explain what we write in English further, do we ?

1. If you create a new framework, or tweaked your c/c++ standart operations etc, you should comment. Anything ONLY you know should be commented. The normal usage of languages are already documented at the official docs, no need to comment those.

2. The most important part is, commenting the weird parts. For example, if you declare an empty function on c#, empty alert on javascript etc, you better comment what is going on briefly, to save time of the developer who needs to change something there.

If you don't, they will say "why do we need that, let's remove this and see what we got". After minutes of compiling and tweaking, they will get what is going on.

@illegaldisease yeah of course the language should not be commented. Shit like:
i++; /*increase i by 1*/
really sucks.

@illegaldisease that's what I meant. Except such cases are rare.

@gnulinuxer4fun Btw., in my driver code, I have often lines like this:
PWR_CR |= PWR_CR_PDDS;
That should be commented what it does, in this example activating the standby mode upon entering deep sleep. The names seem stupid, but they are from the hardware reference manual so that they are easy to look up.
However, when just going through the code, nobody wants to look up the reference manual for every line, that takes too much time.

@Fast-Nop Well, don't take the names from the reference manual. Instead, just make an enum and comment the enum's variables names.

class enum myprintervars {

shutdown, //corresponds to <> in the ref manual

};

@gnulinuxer4fun yeah, I do that for the logical device overall state (i.e. towards upper layers), but that line above is setting a certain bit pattern in a certain memory address - that's idiomatic usage for such code. The RH side is a bitmask define, and the LH side is an integer-to-volatile-pointer-dereference cast define. Enums won't work for that.

Taking the names from the reference manual is mandatory because that allows looking up what exactly these bits are doing and whether there are cross-effects or constraints.

@Fast-Nop okay, then keep them. but leaving a comment after every line of code using them would be tiresome. Instead, you could wrap them in functions and call it stuff like

set shutdown port ()

I don't knwo enough context. I just know, that comments are tiresome and in general not worth the effore and often even hindering

If you can't get the gist in 5 seconds or less, that function should have been commented more gooder.

If you don't know where to start or end, or where the middle is, you need a walkthrough guide.

Anything less is annoying and unproductive.

THESE ARE THE RULES I JUST MADE UP.