[PYTHON] What I thought after working on the "No comment at all" project for a year

at first

I am an engineer at SES. Therefore, my job is to participate in various sites and develop, but what I felt when I was engaged in a team with the idea of ** not writing comments at all ** ~~ and not much documentation ~~ for a year. It is an article that wrote.

Since Java and Python are used for development, samples are described in these languages.

Good thing

First of all, it was good. Broadly divided

--Improve your coding skills --Improvement of writing skills

It is two points.

Improving your coding skills

There are no comments. When writing code in this state, ** variable names, method names, etc. are very important. ** It may be safe to say that coding itself is not so difficult if you can name it properly. In SIer projects, there are many ideas that ** write a lot of comments **. So the code so far looks like this:

Sample1.java

    /**
     * List<Integer>Is received, and the List extracted even numbers is returned.
     * @param List<Integer>Process target List
     * @return Extraction result List
     */
    private List<Integer> searchListValue(List<Integer> a) {
        List<Integer> resultList = new ArrayList<>();
        for(int target : a) {
            if(a % 2 == 0) {
                //If it is divisible by 2, store it.
                resultList.add(target);
            }
        }
        return resultList;
    }

As you can see by looking at this, it takes time to read **, such as `` `resultListappearing multiple times in the same source code and the argument naming isa```. Will take ** Let's try to delete the comment. How about that? It's hard to understand unless you follow the process ...

Sample1.java

    private List<Integer> searchListValue(List<Integer> a) {
        List<Integer> resultList = new ArrayList<>();
        for(int target : a) {
            if(a % 2 == 0) {
                resultList.add(target);
            }
        }
        return resultList;
    }

This kind of code is ** unreadable without comments (it takes time to read) **, which is ** code with comments **, so it is a big growth to stop making this kind of code. was.

Sample1.java

    private List<Integer> filteledListNumber(List<Integer> targetNumList) {
        List<Integer> resultNumList = new ArrayList<>();
        for(int target : targetNumList) {
            if(a % 2 == 0) {
                resultNumList.add(target);
            }
        }
        return resultNumList;
    }

The above code has just changed its name, but I think it's a little easier to read. ~~ This naming may not be good ... ~~

Also, in a ** dynamically typed ** language such as Python or JavaScript, if TypeScript or type hints cannot be used, what data type should be processed in the function name **? Is writing. Depending on the case

test.py

def add (a, b) :
    return a + b;

def addNumber(a, b) :
    return a + b;

It's a story that actually happened, but I've been doing this since there was a case where ** an error occurred when I passed a numerical value to a function that joins strings and called it.

The next change is that ** now calls methods / functions in standard methods and well-known libraries **. I've always recommended using if and for```, and I think methods like stream () `` are disliked, the former I used to use it a lot, but it was a mistake.

The advantage of using standard methods and libraries is that you can now think of ** guessing if there are methods / functions that do the same thing with the same name in other languages **.

--I want to convert the elements of the collection. In Java, `map ()` corresponds, but is it also in Python? --I want to calculate the total value of the collection. Is there a method that can do JavaScript ``` reduce ()` ``?

And so on.

Sample1.java

   private List<Integer> filteledListNumber(List<Integer> targetNumList) {
        List<Integer> resultList = targetNumList.stream().filter(i -> i % 2 == 0).collect(Collectors.toList());
        return resultList;
    }

I also feel that ** if you know these methods, you can read them in the shortest time **, which is a big advantage.

Improvement of writing ability was seen

At first glance, writing skills may decline if you stop writing comments, but you need to write a lot in the ** design document **. (For myself) I feel that there are many people who can work alone ** in projects whose culture is ** do not write comments **, but ** SES is a mixture of boulders. ** ** Information sharing that can be done for newcomers who cannot read the code and those who have not been manufacturing for a long time needs to be communicated not only by the code but also by using the ** design document **.

I tried to write this design document in quite detail. ** The part that I can't understand by reading the code is so that I can look at the design document and find out what kind of processing I want to do **.

In the process, my writing skills improved.

(Extra edition) Easy maintenance

** I was involved in a project where the comments I left were not changed and were inconsistent with the current process **, but I wrote comments compared to the hardships at that time. I feel that it is easier not to have it.

trouble

From here on, it's a problem. Classification is

――It can be difficult to read the code of the person who left the project. --Quality fluctuates depending on the level of the person in charge

It is two points.

It can be difficult to read the code of the person who left the case

Many of the projects that I participated in at SES had a lot of traffic. ** I remember that the code of the person who supported it was a high level Java logic, and it was very difficult to read. ** **

If this situation accumulates, ** everyone can maintain it if they read the code properly, but it is on fire and there is no room for it. ** That happened. In such a case, I would like to leave a comment as much as possible.

Quality fluctuates depending on the level of the person in charge

Do not comment. The project didn't even have a ** whole system documentation or code review. Of course, there are also coding standards. ** In other words, it consisted of making all deliverables the responsibility of the person in charge **.

In these cases, I feel that the comments are valid.

--Newcomer coding for the first time ―― 5th year me --15th year veteran (lead engineer)

Each of the deliverables created by each of them had individual tastes clearly expressed, so there was a difference at a level that seemed to be a completely different language. ** I want to share information in Japanese at such times! I strongly felt. ~~ I blew out a fire because I couldn't share it. ~~

Sample1.java

//Rookie's code
    private List<Integer> searchListValue(List<Integer> a) {
        List<Integer> resultList = new ArrayList<>();
        for(int target : a) {
            if(a % 2 == 0) {
                resultList.add(target);
            }
        }
        return resultList;
    }

//My code
   private List<Integer> filteledListNumber(List<Integer> targetNumList) {
        List<Integer> resultList = targetNumList.stream().filter(i -> i % 2 == 0).collect(Collectors.toList());
        return resultList;
    }

//Veteran code
   private List<Integer> filteledListNumber(List<Integer> targetNumList) {
        return targetNumList.stream().filter(i -> i % 2 == 0).collect(Collectors.toList());
    }

  

All of these are the same process, but with a different approach. The difference in this approach ** occurs in all source files. ** So if you want to create a culture where you don't write comments, ** you have to focus on other processes or the limit will come someday. ** **

At the end

It's short, but that's it. It's a personal impression, but the comment is

--There is no choice but to communicate using comments --Intention of original logic used only for that project (it does not appear even if you google) --Comment maintenance is easy

I think that it is effective to describe in such a case.