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.
First of all, it was good. Broadly divided
--Improve your coding skills --Improvement of writing skills
It is two points.
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 is
a```. 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.
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.
** 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.
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.
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.
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. ** **
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.
Recommended Posts