2- Why/How to write "Comment"? What is Clean Code?

CleanCode

Have you ever been significantly impeded by bad code? If you are a programmer of any experience then you’ve felt this impediment many times. Indeed, we have a name for it. We call it wading. We wade through bad code. We slog through a morass of tangled brambles and hidden pitfalls. We struggle to find our way, hoping for some hint, some clue, of what is going on; but all we see is more and more senseless code.

Of course you have been impeded by bad code. So then—why did you write it?

Were you trying to go fast? Were you in a rush? Probably so. Perhaps you felt that you didn’t have time to do a good job; that your boss would be angry with you if you took the time to clean up your code. Perhaps you were just tired of working on this program and wanted it to be over. Or maybe you looked at the backlog of other stuff that you had promised to get done and realized that you needed to slam this module together so you could move on to the next.

We’ve all done it.

We’ve all felt the relief of seeing our messy program work and deciding that a working mess is better than nothing. We’ve all said we’d go back and clean it up later. Of course, in those days we didn’t know LeBlanc’s law: Later equals never.

Here I am again with the 3rd article of the 0- Advanced Software Development article series. I wanted to start with a short excerpt from the chapter of Clean Code titled Bad Code. With the hope that you will develop software that you do not say "later"...

A good software developer writes quality code. The quality code is written with attention to many important issues such as architectures, tests, ci/cd, solid etc. Sometimes, no matter how careful we are, after a while, the work we receive from our managers, especially with the "URGENT" code, can turn into a mess, which we call spaghetti code. The "URGENT" code not only makes us panic and lowers the quality of our code, it is also losed us more time at the end of the day. Because it will always be more difficult to edit these codes later or add new features to this software.

Writing clean code is what you must do in order to call yourself a professional. There is no reasonable excuse for doing anything less than your best. Robert C. Martin Clean Code

Of course, within the scope of this article, I will not translate the Clean Code book. In this series of articles, I talk about the issues that a person who wants to develop Advanced Software should pay attention to, focus on and research. If you want to develop advanced software, I can definitely say that it is a book you should read. It is certain that you will make much more profit than the time you spend reading the book. I'll leave the link here for those who want to read it. Clean Code

What are the features of clean code? To answer the question in items:

1- It should be readable, changeable, expandable and easy to maintain.

2- It should be written in accordance with SRP principle. To give an example of the Single Responsibility Principle, we can say that each method should serve only one purpose.

3- Architecture should be created appropriately. The purpose of all files should be clear. It will be easier to find what you are looking for. It saves time.

4- There should be no commented code blocks called zombie code. This will only confuse team members. Why was this written? Will it be needed in the future? It is losed time with questions like this.

5- All tests must be written and passed. In this way, it can be easily determined that future developments will not affect the old sections.

6- Each file in the project must contain codes only in the language specified in its extension. For example, instead of writing JavaScript/CSS in a file that ends with .php, creating a .js/.css file will provide a more organized structure.

7- It shouldn't be necessary to study all the code to understand any function. A simple action, such as an meaningful name , saves team members time.

8- Code duplication should be avoided. A method/function that does the same job should not be written over and over again.

As a result of my experience and research, I can say that you can write better quality code if these items are followed. That supported these, there are the following sections in the Clean Code book:

Meaningful Names, Functions, Classes, Exception Handling, Appendix, Formatting, Comments, Systems, Emergence, Concurrency, JUnit Internals, Smells and Heuristics, Refactoring, Successive Refinement, Unit Tests, Boundaries, Objects and Data Structures.

It is not possible to explain them in a single article. One or more articles should be written for each title. Here in the article I wrote only the section names. I'm thinking of writing articles on application examples that I will use Swift language for these section titles in the future.

Comments

As I mentioned before, the best comment is the one that is not needed. Code that is self-explanatory is best. The comments we try to explain our code are an indication that our code is not good. The best project is the one for which the README file is sufficient and does not need comments.

So why and how to write a comment?

We can use comments as a communication tool between team members. We can use it to indicate how much work has been done, or to tell another team member what to do next. When assigning a new task to a team member, after the file is opened, which functions should be written in this file can be written in the form of a comment block at first. Of course, comments written in this way should be deleted after their functions are finished.

We should use it to explain why a function is written, not to explain how it is written. Although there are many resources on how to write code, there are not enought resources on how to write comments.

Any fool can write code that a computer can understand. Good programmers write code that humans can understand. Martin Fowler

Some sources say that comment lines should be at least as many as lines of code. I think that this point of view does not reflect the truth completely. Because measuring the number of comment lines in a program is easy. But measuring comment quality is not easy. An unwritten comment is better than a bad/unnecessary comment.

Writing good comments is harder than writing good code. Your compiler doesn’t check your comments so there is no way to determine that comments are correct. Peter Vogel

How to write a Clean Comment?

1- Comments should not duplicate the code
2- Good comments do not excuse unclear code.
3- If you can’t write a clear comment, there may be a problem with the code.
4- Comments should dispel confusion, not cause it.
5- Provide links to the original source of copied code.
[Source: https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/]

As Stack Overflow co-founder Jeff Atwood has written, “Code Tells You How, Comments Tell You Why.

A comment with release notes for the language or framework used in the first part of the files might be helpful. At the same time, the name, surname and e-mail address of the person who created the file can be used to indicate who should be contacted in case of potential problems in the future. The comments that you explain why you wrote the functions you wrote in a short and concise way will be a source for the person who will continue to work on the same project after you.

When we first start learning a language or framework, we feel the need to take little notes to ourselves. It's okay if we keep these notes as comments on our personal projects. We can then use this information over and over again as a documentation we prepare for ourselves.

The most important reason why comments are not liked by most developers is that they are not updated. Comments are usually left as they were originally written. A change made in the code is not reflected in the comment. The code becomes irrelevant to the comment made after a while. If you are not going to update your comments, it would be best not to write comments. Because your teammate is losed time trying to understand the misspelled comment line.

Unused code that convert to a comment is another biggest mistake.. Such a situation is likewise "Why was it written? Will it be used?" It causes you to steal the time of your teammates with questions such as. When writing comments, try to write comments that can save time for your teammates, not stealing their time.

Don't try to write comments for every code block. Take care to write comments at the function/method level. Use comments to tell why you're writing, not to explain your code. Try to keep the comments as up-to-date as possible. Feel free to delete it if no longer needed. If you pay attention to what is written here, there is no doubt that you will be a better team member.

According to the Clean Code book, the majority of comment lines are used to explain/hide badly written code. If you're commenting for this purpose, I suggest you go back and fix your code. I am aware too. Using comments has a bad reputation. But let's face the fact that it can be a great tool if you use it right. When working on a project, transfer your thought process to convey why you did it to people who will work on that project in the future.

Again, I tried to fit a lot into a single article. These are important issues that need to be read, researched and applied. We are in a fast developing industry. We need to be in constant research and study. If you search, you can find detailed documents about these topics that I mentioned at a simple level.

In the Advanced Software Development series:

Previous article: "1- Software Architectures".

Next article: "3- Why Should I Write Tests While Developing Software?".

Don't forget to like if you think it's useful :)

Always get better…