openAV-Luppp
openAV-Luppp copied to clipboard
openAVproductions
Better commentation of classes and functions
Althought the code is very easy to read and most a little more complicated lines of code are commented, its kind of hard to get the bigger connection in the code. Sometimes when i look for something, i dont need to know how a class or function works internally, its enough to know what it does. But since there are no information for most of the classes and functions, i need to read them to get the hole context.
Maybe this is just because i am not used to C++ but in general it might be an good idea to add some comments at least for new code to make it easier in the future to get into the code base.
@georgkrause, so this issue is about adding docstrings to all classes and methods?
Well, this would be amazing, but its a lot of work and since it does not bring any feature i dont know if someone is motivated to do this. My intention was more to remind everyone to maybe add one or two docstrings if one passes by...
Is the problem really that the functionality of a class isn't known? Or is the real problem that it is hard to see how multiple classes interact, or what "owns" other instances? My reading of the 1st post is that the "overall design" is the hard part to understand, in which case the correct solution is to create a "design document", which details how the classes interact, and which classes are owned by which.
@georgkrause - would such a design document solve the issue you're having?
Such a design document would be great! This would help me a lot.
But also if i read code i often dont understand what a class or function does, which isnt in my focus right now. so i need to read this, two. Having docstrings would help a lot on this issue. This is getting much better from time to time, so i want this comment stuff mostly for other users new to the project. if we all think about writing some docstrings when we edit a file, this should help a lot.
In general i think there is never too much documentation...
@coderkun and i thought of adding a Doxyfile to the repo, i already have one and could file a PR in the next days.
@harryhaaren do you want docstring comments for classes/functions in the header or source files?
@georgkrause, usually you add docstrings to both, in the header for what a class/method does and in the source file for how this is done.