Document Codebase #13

New Issue

Open

opened 2023-07-22 20:29:57 +00:00 by antifallobst · 4 comments

antifallobst commented

2023-07-22 20:29:57 +00:00

Owner

The whole codebase should be documented with comments above functions, struct members, etc...

bpeetz commented

2023-07-22 21:01:39 +00:00

Owner

Isn't some code self documenting?
I'm not arguing against comments above special code, like for example some std library code.

But within Trinitrix these parts should be rather rare, as we work on a higher level. I'm suggesting, to let the high level code document itself, by reducing nesting to a maximum of three levels and reduce inlined variables, this allows to add function/variable names, which describe what the code does. This seems to me, to produce better readable code.

Obviously the low level stuff, or the parts, where complexity can't be avoided should be documented with the conventional methods.

Isn't some code self documenting? I'm not arguing against comments above _special_ code, like for example [some std library code](https://doc.rust-lang.org/src/alloc/collections/vec_deque/mod.rs.html#285). But within Trinitrix these parts should be rather rare, as we work on a higher level. I'm suggesting, to let the high level code document itself, by reducing nesting to a maximum of three levels and reduce inlined variables, this allows to add function/variable names, which describe what the code does. This seems to me, to produce better readable code. Obviously the low level stuff, or the parts, where complexity can't be avoided should be documented with the conventional methods.

antifallobst commented

2023-07-23 06:17:44 +00:00

Author

Owner

For sure code should align certain readability rules. CodeAesthetic has some great yt videos about that stuff.
But readable code often isn't enough, because stuff that makes sense in your head, can be confusing as fuck in another ones head.
I think a one liner above every function can't hurt and helps new contributers to understand the codebase. It also helps text editors to generate help previews, so you can see what the function does without diving into its source.

What do ya think about an indentation max level of 4?

For sure code should align certain readability rules. [CodeAesthetic](https://www.youtube.com/channel/UCaSCt8s_4nfkRglWCvNSDrg) has some great yt videos about that stuff. But readable code often isn't enough, because stuff that makes sense in your head, can be confusing as fuck in another ones head. I think a one liner above every function can't hurt and helps new contributers to understand the codebase. It also helps text editors to generate help previews, so you can see what the function does without diving into its source. What do ya think about an indentation max level of 4?

bpeetz commented

2023-07-23 07:25:28 +00:00

Owner

Well theoretically documenting stuff with a one line works, but if the quality isn't specified we end up with stuff like:

/// Turns a string into an integer
fn turn_string_to_integer(...) {...}

In that case, the comment does nothing, besides wasting one line.
But in a general case, a one liner above these thing would be useful.

I wouldn't enforce a precise indentation level, as some rust expression aren't complex but space inefficient (match statements). But yeah, everything above a level of 4 should probably be a red flag.

Well theoretically documenting stuff with a one line works, but if the quality isn't specified we end up with stuff like: ```rust /// Turns a string into an integer fn turn_string_to_integer(...) {...} ``` In that case, the comment does nothing, besides wasting one line. But in a general case, a one liner above these thing would be useful. I wouldn't enforce a precise indentation level, as some rust expression aren't complex but space inefficient (match statements). But yeah, everything above a level of 4 should probably be a red flag.

antifallobst commented

2023-07-26 20:49:50 +00:00

Author

Owner

Well, I wouldn't force comments over everything.
If something has a really obvious name, just don't comment it...

Well, I wouldn't force comments over everything. If something has a __really__ obvious name, just don't comment it...

This repo is archived. You cannot comment on issues.