Have you ever tried to solve a very important problem doing some programming but found stacked because you can not understand the code that you wrote the week before?

If you are writing code this is not happen yet in your life, it is doom to happen soon. If you plan to implement something as part of your thesis. I can guarantee you that it will happen!

The problem of how to write comments into the code is fairly common and well understood in business. Companies, in the attempt to mitigate this phenomena, create guidelines on how to comment the developed code in order to make it understandable by different employees.

Good comment practices can be applied in all possible programming languages. The goal is not to improve the speed or the consumption of memory. It is more related to focusing on let other humans understand what has the program does and why. By the way, that “other human” most of the time is your future self!

1: Write comments when you are writing the code

You should considering writing comments when you are writing the code itself. Otherwise, you will probably forget half of them and will spend twice the time in doing this task. In general, you will be the primary user of these comments as often will have to read again the code in order to modify its functionalities.

2: Every class a and functions should start with a description

A code should start with a general description of the program containing:

• The problem(s) that the code solves
• The data-structure(s) used in the code.
• What algorithms and techniques, are used in a particular piece of the program

Every functions should have a description of the general idea and the input and output should be explained

3: What you write matter

Know how to write a comment is more then just writing comments for the sick of writing comments . Consider the following when deciding what to write:

• Do not comment the obvious
• Do not comment what the code is doing
• Comment why you are doing it.

Below you can find a couple of videos that share some insight on how to comment. This first share a few best practices using Eclipse and Java as a framework of reference. The author also makes the a good point when he says that good code should be self-explanatory and shows a concrete example of that. Similar points can be made with Python code as well.

This video explain another set of best practices when commenting the code. However instead of focusing on Java use Python as reference language.

Independently of the language that you are using both these videos can help you in understanding common best practices that you should use in your code, Java, Python or anything else.

Other useful resources of understanding the basic of programming includes:

• Why you need an IDE
• The Basic of Object Oriented Programming (OOP)

And if you believe that you are a super talented programmer this article should put things in perspective:

• How to design a good API

Best practices on how to #write #comments in your #code. #programminglife of #SoftwareEngineer . #java and #python examples
Share on X

The post Best practices on how to write comments in your code appeared first on Francesco Lelli.