English


Let's talk about the comments.

If we take a closer look, it is easy to notice that a few types of comments could be identified basing on how a developer located the comments in the code. Similarly to the code blocks, empty lines should be respected because they define chunks of information. The three comment types are: independent, leading and side comments.

The independent comments are those which occupy one or many lines and separated from anything else by at least one empty line. The independent comment lines do not contain anything but comments.

The leading comments are quite similar to the independent ones with one exception. The very next line after a leading comment is a Python statement. A developer did not insert an empty line between the comment and the following block and most probably this is meaningful - the comment is for the following block.

The side comments are those which are located to the right of the statements. There are a few important details about side comments. A code block may occupy a few lines and a developer may want to provide a comment for a certain line in the block. This fact should be respected. Another detail is that sometimes a developer may want to provide more than one line of comments for the last statement in a code block. Cases like that should also be respected in graphics.

Theoretically it is possible to introduce a trailing type of comments - similarly to the leading type with the difference that there is no empty line between a statement above and the comment. This however seems to have a very minor practical sense. Developers rarely comment something which is located above. They rather use a leading comment or a side one. Therefore I decided not to introduce a trailing type of comments.

So, how could these three distinguished types of comments be drawn on a diagram if they are properly identified?