DEV Community

Clean code & programming principles – The ultimate beginner’s guide

Spyros Argalias on May 14, 2021

This article is the beginner's introductory guide to programming principles. First we're going to examine what good code is. The qualities of good...

Read full post

Cooper Riehl • May 15 '21

Wow! I've been working on an article covering about 5% of what you talked about here, and now I guess I don't need to post it 😅

For real though, this is all amazing advice. You've touched on so many ways to write clean, maintainable code. You explained each topic just enough to give people an idea of how to apply it, without overwhelming them. I'm bookmarking this article to share with all my friends who are learning programming.

Spyros Argalias • May 15 '21

Haha, thanks very much Cooper. I'm sure the article you're working on will be very useful, so it will great if you still write it :).

That's awesome. I'm glad you find it good enough to share. Thank you :)

Enmanuel Marval • May 14 '21

Muy buen artículo :3 Me hubiera gustado leer algo así hace años

Spyros Argalias • May 14 '21

Thank you very much Enmanuel. I really appreciate that :)

I don't speak Spanish so using Google translate:
Muchas gracias Enmanuel. Realmente aprecio eso :)

Cody Tilkins • May 20 '21

I think it would be worth mentioning commenting, as it makes the 'we dont remember anything' non-existent. Proper commenting explains context, inputs, outputs, and intended purpose.

Spyros Argalias • May 20 '21 • Edited

Thanks for the comment @tilkinsc .

I actually have a stance against commenting, just like Uncle Bob.

Reasons I advise against comments

If you use good names and good code organisation you don't need comments.

For example, if your method is named "addTodo", in your Todos model class, you don't need a comment to describe what it does. The name already describes it enough. A comment would be redundant. This is how it should be with all code, naming and comments.

If you need a comment to explain something, the code could have been simpler and better labelled (named) so the comment wouldn't be needed.

If you need comments to explain connections and dependencies that you wouldn't otherwise know were there, then the code isn't independent / decoupled enough. It should be refactored so that the comment is not necessary.

Also, comments make changes more difficult. If you update or change something in the code, you need to also change any relevant comments, which is additional work that slows you down.

Finally, someone may not update the comment when they change the code. Then, you have an even bigger problem on your hands because the comment now says wrong information. But, the next developer to read the comment wouldn't know it's outdated. The comment may say something like "this is dependent on X". The developer may investigate further, only to waste their time, because the comment is no longer true. Or they may be afraid of changing anything because of the comment. Or there could be many other problems.

In summary, my reasons are that:

comments should not be necessary
comments are additional work to update
comments may be outdated and contain false information, potentially causing large problems

Therefore, I avoid comments in almost all of my code. I've also worked in many codebases. The ones that didn't use (need) comments were substantially easier to work in.

Exceptions and other cases

The only rare exception, is if you're working in some especially bad area of the codebase. If you need a comment to point out something important, you write it, but that should be the exception. In my experience, that's only been in areas with bad code in the codebase.

I think commenting as documentation is fine though. E.g. if you have a tool that picks up comments in code, written in a certain format, and auto-generates documentation for them.

Also, I think documentation about your code is fine. That's documentation that, for example, describes the architecture of your code, main classes and how they fit together. These are different from detailed comments in code. They're more like an introduction to your codebase, or certain parts of it, for new developers to the company or the particular team.

But that's just my opinion. I welcome your thoughts and even counter-arguments.

Edit: changed "Todo class" to "Todos model class"

Cody Tilkins • May 21 '21

What you are suggesting tends to make code bases more complicated with more steps. The problem translates into piecing together many different functions under many different hierarchies. It tends to prove that procedural programming is superior in that regard. Comments for everything is not necessary, but I've found you wonder if a specific function supports a feature. A good programmer with foresight makes comments for other users to understand edge cases as well as makes proper tests to prove that everything works.

Spyros Argalias • May 21 '21

Thanks for the reply. I agree with tests and I'm a big proponent of them :).

I also agree that if a comment would be useful and save someone a headache, it should be added. My point was only that comments should be the last resort compared to code that's obvious and sensible so it doesn't need comments.

I won't be adding it to the article for now because I don't see it as part of the fundamentals. More like a tip, that also needs the appropriate warning of only using comments as a last resort.

Having said that, I really appreciate that you took the time to make a suggestion. Thank you.