While we all agree documentation is good in general, there might be some differences on how to do documentation/comments.
Example is a fetch_subvolume function
https://github.com/equinor/vds-slice/blob/57b836c97c3494e4279b5236c12f045ad14d9e8a/internal/core/cppapi_data.cpp#L241-L247
Do we want to document such general parameters as handle and subvolume?
Do we find we need to document from and to?
Are we fine with just general description or do we want to mark every single parameter? Would it lead to too much "horse: horse is a horse" aka pointless descriptions as developer can't come up with anything useful.
Another example is index translation in https://github.com/equinor/vds-slice/blob/57b836c97c3494e4279b5236c12f045ad14d9e8a/internal/core/cppapi_data.cpp#L293-L299
Should we try to rename variables, would it help? Should we add a "what we are doing" comment? Should we create additional structures just so this code is more understandable?
Basically where lies the border between of "you get it once you are familiar enough with the code, adding and maintaining it is just waste of time" and "but I need docs/comments to understand the code NOW".
While we all agree documentation is good in general, there might be some differences on how to do documentation/comments.
Example is a fetch_subvolume function
https://github.com/equinor/vds-slice/blob/57b836c97c3494e4279b5236c12f045ad14d9e8a/internal/core/cppapi_data.cpp#L241-L247
Do we want to document such general parameters as handle and subvolume?
Do we find we need to document from and to?
Are we fine with just general description or do we want to mark every single parameter? Would it lead to too much "horse: horse is a horse" aka pointless descriptions as developer can't come up with anything useful.
Another example is index translation in https://github.com/equinor/vds-slice/blob/57b836c97c3494e4279b5236c12f045ad14d9e8a/internal/core/cppapi_data.cpp#L293-L299
Should we try to rename variables, would it help? Should we add a "what we are doing" comment? Should we create additional structures just so this code is more understandable?
Basically where lies the border between of "you get it once you are familiar enough with the code, adding and maintaining it is just waste of time" and "but I need docs/comments to understand the code NOW".