Guideline Idea Tracker

[geeknoid]

Note, names and guidelines are tentative, this is mainly a braindump of my (@ralfbiedert) collection of notes from reviews and conversations:

Common / Unsorted

• M-NO-STATIC-NUMA - Avoid statics as lookup tables (might end up in wrong NUMA region), use thread locals
• M-CATCH-UNWIND - catch_unwind is only last resort, servers should gracefully terminate
• M-PANIC-MESSAGES - custom panics should have helpful messages (compare expect())
• M-PARAMETER-POSITIONS - important ones go first, "DI"-like last, closures always last
• M-NO-FQP - Don't FQP paths in code (TODO: should be clippy lint already, probably just update other guideline)
• M-LOG-NOT-PRINTLN - Don't use (e)println in production!
• M-LOG-ERRORS-XXX - Some guideline where to approach logging (relative to error position, only stack upmost?)
• M-LOG-GRANULARITY - Rules on what's generally acceptable to log and how much, and what not
• M-TODO-UNREACHABLE-UNIMPLEMENTED - When are they fine to have?
• M-TYPE-DEFAULT-NEW - ::default() implies ::new() on public types
• M-URI - What to use for Uri and URL?
• M-TESTABLE-CLOCK - Time dependent code should be testable
• M-NO-DOUBLE-ARC - Before applying Arc, check if what you wrap already has an inner Arc ... (and friends)
• M-MUST-NOT-PANIC - Outline situations where panics must not occur
  • File parsers, protocol parsers, user input parsers should return errors when encountering unexpected input values.
  • All I/O handling should return errors when encountering I/O problems and not panic
• M-EXTENSION-TRAITS - Extension traits are for foreign types, not for your own ones.
• M-BOX-STR - When to use Box<str> and friends, when to use String.
• M-SHRINK-TO-FIT - On reducing allocation size of HashMap and friends once immutable
• M-IMPL-INTOITERATOR - (Mostly on Copy types?)
• M-META-DESIGN-FOR-USERS(?) - As a library author you should do the hard thing that your users have it easy, not other way around. Esp. don't take shortcuts that significantly limit your user's ability to use your crate.
• mod.rs over foo.rs + foo/?
• Add rule that projects must have some command that runs "just like CI" to avoid wasting hours to rerun the same things again and again until some arcane test maybe passes
• ffi: core vs ffi layer, core should have 99% of functionality, FFI only translation
• Trait naming should follow std conventions.
• How to test / where to put tests and utils / differentiating unit vs integration tests / visibility of testables
• When it's ok to re-export things from other crates?

Performance

• Split out HOTPATH into multiple guidelines (M-AVOID-ALLOCATIONS, M-AVOID-REHASHING, M-APPROPRIATE-HASHER, ...)

Other areas that potentially need some guidelines:

• M-TESTABLE - Making components/designs so they can be used in tests (creating mocks, fakes, etc)
• M-ASYNC-FN - Should functions return impl Future<Output = X> or just async fn f() -> X ?

Ideas on improving AI efficacy:

• Keep designs simple and verbose over intricate
• Design for concrete types
• Design avoiding lifetimes
• Encourage smaller files and clean interfaces
• Keep / request a structured type / project layout file (maybe not?)