Add style guide

[rennergade]

We want to find and add a style guide for the projects to the docs.

[m-hemmings]

Suggest we begin with this:
https://doc.rust-lang.org/nightly/style-guide/advice.html

And see what, if anything, we want to change

[JustinCappos]

I use clippy with a specific set of settings (listed in fdtables). Is this something we can do throughout? Any complaints / thoughts?

…

On Mon, Jan 13, 2025 at 2:21 PM MHemmings ***@***.***> wrote: Suggest we begin with this: https://doc.rust-lang.org/nightly/style-guide/advice.html And see what, if anything, we want to change — Reply to this email directly, view it on GitHub <#17 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAGROD5WAN2XMPF6X67DPFL2KQG3LAVCNFSM6AAAAABUWPZHOOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDKOBXHE4TQOJSG4> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[rickmcgeer]

Thanks for the guide, Nick. I always recommend to everyone that they start with the Tcl/TK Engineering Manual, here: https://www.tcl.tk/doc/engManual.pdf. It's 22 pages, but it can be leafed over. The Tcl/TK manual is a style guide for a specific project in a specific language (C), but its overall lessons are worthwhile for everybody. At least they were for me, And they are, basically: - Your code has to be easily understood by everybody on the project, including you six months from now after you've forgotten you wrote it. The reason to have a uniform style is just so people don't spend time trying to decipher unfamiliar code - Use meaningful variable names. - Avoid tricky, hard-to-understand code. - Don't nest too deep. - Document as, or before, you code. - Keep functions to a page (~30 lines or so, WITH COMMENTS). If it goes longer than that, it's hard to understand and read and needs to be re-factored. - The style/standards have to work for the whole team, and everyone together is smarter than any one of us... Some other lessons I've learned over the years: - DRY: Don't Repeat Yourself. (Albert Rafetseder, a student/colleague of Justin's, taught me that one). - Everything is part of the code. Makefiles, setup scripts,download/analytic scripts, tests, data, etc., are all part of the production artifact. Github it all, document workflows in markdown files, etc. - Every coding community has informal standards for naming and formatting, so respect those. For example, JavaScript uses CamelCase everywhere; Python uses snake_case except for classes, which use CamelCase for the clases and snake_case for functions and variables. - Centralize functionality. One of John Ousterhout's criticisms of Object-Oriented programming (really inheritance) was that a programmer needed to walk to the root of the hierarchy to understand the functions of an object. If something inherits/relies on functionality provided elsewhere, provide a pointer and document it. - Make sure the style guide fits the IDE/editors of *everybody* on the team.

…

On Mon, Jan 13, 2025 at 11:21 AM MHemmings ***@***.***> wrote: Suggest we begin with this: https://doc.rust-lang.org/nightly/style-guide/advice.html And see what, if anything, we want to change — Reply to this email directly, view it on GitHub <#17 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFAHA7U5FQ7ECPCUYO6FO32KQG3LAVCNFSM6AAAAABUWPZHOOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDKOBXHE4TQOJSG4> . You are receiving this because you were assigned.Message ID: ***@***.***>

-- Rick McGeer ***@***.*** +15103346004

[rennergade]

I use clippy with a specific set of settings (listed in fdtables). Is this something we can do throughout? Any complaints / thoughts?

This seems great. I quickly looked at the fdtables repo and didn't see this. Could you share and we can add this in some way?

[rennergade]

We probably want to go back to using cargofmt as well.

[JustinCappos]

I use clippy with a specific set of settings (listed in fdtables). Is this something we can do throughout? Any complaints / thoughts?

This seems great. I quickly looked at the fdtables repo and didn't see this. Could you share and we can add this in some way?

It's in the comments at the top of lib.rs for fdtables. Lines 21-77

We can think of this as a base and adjust as is needed. Most likely, we want to centralize this so we don't need to update it a ton of places if we ever change it.

[rennergade]

Thanks!

Link to clippy code so we can easily reference this from the thread: https://github.com/JustinCappos/fdtables/blob/main/src/lib.rs#L21