Sorce code - why don't you increase comment lines ?


#1

Hallo to all Synfig fans, users and especially developers,

I have seen the current Synfig’s sorce code. And in the next weeks I will start to study it.
I think that collaborators in develpoment could better understand the inner structure and the underlying algorythms just increasing the number of comment lines. It seems to me there is a lack of comment in the source code.
The more commented is code, the better understood it will be.
I think it would be better than write down more wiki pages for developers.
“Open” source means visible code, anyway there are not just professional developers here, but even hobbyist.

My two cents
Best wishes
Tiber


#2

Hello

Has you said … it’s mostly hobbyist coders who do the daily job… welcome to your 2cents comments when you will study the code :wink: … also you can note that the number of comment increase each month …slowly, but increase :wink:


#3

Hi Tiber,
I’m sorry but I have to say that the best comment is the one you don’t need to write. The code should be clear enough to be read. If it is not, the code should be refactored, not documented. Comments also get outdated and make the whole thing more difficult to understand.

There is really a lot of code that needs to be refactored in synfig. If you will start studying and improving the code, I would recommend that once you understand some part that you think it is not very readable, create some unit tests and refactor it. It may be only a variable name change or a method extraction but it is valuable if it improves the code readability.
I have a branch where I started creating some unit tests to the core. You are very welcome to add more. Branch on GitHub Issue in bug tracker

Anyway welcome to the development. I do not mean to be unwelcoming at all, just you know, I have other two cents :slight_smile:

Best regards,
eldruin.


#4

You are both right, but…

A project always need comments.
Refactoring is good to improve readability, but it is mostly focused in implementation.
The comments in the code should be mostly used for generation of automatic documentation (Here)
But this is only the “coding part”.
What is the most important is the concept, the description and the reason of the choice for some algorithm.
Drawings of overviews, with more and more details when focusing on specific parts.
This page is a perfect example.
Always go from the global to the specific.
You are coders/developers (I am too IRL), you always need documentation.
Even non-coders could suggest improvements if they know where to “insert” some concepts.

Source code should be readable like musical parts, proper indentation, alignment, constants and with use of spaces between the terms.
Unless you have to pay taxes for these spaces :smiling_imp: