Space Camel Comment Style & Layer Comment Style

> for Japanese Pages

Space Camel Comment Style & Layer Comment Style
1. Summary
In this post I propose Space Camel Comment Style and Layer Comment Style as a way of thinking of programming comment style.
FYI.

2. Introduction
Comment statements of programming source code is one of the important elements in a scalable system.
If there are no comment standards in the project, the comment style varies according to programmers.
Also, I often hear the following voice from many programmers.
“I do not know what to write in comments.”
“I do not know the granularity of comments.”
In this post I propose Space Camel Comment Style and Layer Comment Style as a way of thinking of programming comment style.
I will not mention any comments, FooDoc, annotations or other comment styles other than the logic part here.
Also, I will not mention about the presence or absence of comments by elegant code.


3. Cooment Style
3-1. Space Camel Comment Style
Because I could not find a general definition, I would define it as “Space Camel Comment Style” here.
This is a camel type comment style like an object-oriented method name.
It is a form that puts a space in words of the method name.

for Example:
# set Controllers and View Resources
Reason why this is useful.
In programming and the IT industry, it is not unusual to omit English "articles" in naming.
(I do not mention here about countable nouns, uncountable nouns, plurals.)
Regarding memory reservation, although it is already talk of the past, English grammar strict to naming greatly deteriorates readability.
Also, there are many cases not related to the context before and after.
Top programmers accustomed to simple naming to improve readability may not feel discomfort even with this format.
The trick is to think about the process flow in terms of behavior.
It is similar to method approach.
As in the case that you mothodize the logic, the scope of the comment is also determined by the range of processing to make one behavior.
You just write a comment as if you naming the method for the behavior.
This will clarify the granularity and style of your comment.
Also, since it is not affected by reusability or conflict like method name, you should be able to write much more flexibly than method name.
However, this is not the case if you have to explain a lot in comments.
In that case, for example I might do as follows:
# Notice: description...

3-2. Layer Comment Style
Because I could not find a general definition, I would define it as “Layer Comment Style” here.
In the source code, even if indentation of the same layer, the layer of processing may be different.
In such a case, a comment style conscious of the layer of processing like markdown head is useful.

for Example:
# set Controllers and View Resources
processing...
## for Controllers
processing...
## for View
processing...
Thus, by making the comments multi layered, you may be able to increase the readability of the layer of behavior.


4. Conclusion
In this post, I proposed two programming comment styles, Space Camel Comment Style and Layer Comment Style.
For Space Camel Comment Style, I think that it is applicable to commitment sentences.
Whether your programming orientation is object-oriented or procedural, low-layer processing has to be written somewhere.
These comment styles would be particularly useful for describing such low layer processing.