General development guidelines for EasyScience

[rozyczko]

These should be obvious to anyone doing software development, but it might be useful to codify this.
Stolen from user-level CLAUDE.md and modified for our group.

Development Guidelines

Philosophy

Core Beliefs

• Incremental progress over big bangs - Small changes that compile and pass tests
• Learning from existing code - Study and plan before implementing
• Pragmatic over dogmatic - Adapt to project reality
• Clear intent over clever code - Be boring and obvious

Simplicity

• Single responsibility per function/class
• Avoid premature abstractions - don't overengineer "for future."
• No clever tricks - choose the boring solution
• If you need to explain it, it's too complex

Technical Standards

Architecture Principles

• Composition over inheritance - Use dependency injection
• Explicit over implicit - Clear data flow and dependencies
• Test-driven when possible - Never disable tests, fix them

Error Handling

• Fail fast with descriptive messages
• Include context for debugging
• Handle errors at appropriate level
• Never silently swallow exceptions

Project Integration

Learn the Codebase

• Find similar features/components
• Identify common patterns and conventions
• Use same libraries/utilities when possible
• Follow existing test patterns

Tooling

• Use project's existing build system
• Use project's existing test framework
• Use project's formatter/linter settings
• Don't introduce new tools without strong justification

Code Style

• Follow existing conventions in the project
  • E.g. naming in https://github.com/orgs/easyscience/discussions/16
• Refer to linter configurations and pyproject.toml, if present
• Text files should always end with an empty line

Important Reminders

NEVER:

• Disable tests instead of fixing them
• Commit code that doesn't compile
• Make assumptions - verify with existing code

ALWAYS:

• Commit working code incrementally
• Update plan documentation as you go
• Learn from existing implementations
• Stop after 3 failed attempts and reassess

[seventil]

Generally agree, except for If you need to explain it, it's too complex - complex problems lead to complex solutions. Besides, you always need to explain concepts, which others are not familiar with - that does not prove they're unnecessarily complex.

Some other things I have issue with, it's just hard to put my finger on it, for example Handle errors at appropriate level - what's appropriate is context-dependent and so the rule sounds too abstract for me.

[seventil]

But I have to mention that I really like the idea of unified and codified approrach to work, even though it will take some time to hash the specifics out

[rozyczko]

I think too complex is when we all start scratching our collective heads, trying to figure out what this code is actually doing and how. We've had too much of this recently, so specifying the complexity removal clause probably makes sense.

We are all software devs, so even complex problems should be understood given a well-thought-out algorithm and decent documentation with unit tests.

[henrikjacobsenfys]

I think this is a good idea. I also think we should strive to make it as concrete as possible. For example: "Incremental progress over big bangs - Small changes that compile and pass tests" could have concrete numbers and desired behavior, such as: "Aim to make PR's no longer than 500 (?) lines of code. If your PR is growing bigger than this, discuss with the team at standup".

We could also add something about what to do if you're stuck/need help.

I like the link to the naming convention ADR - more such links would be useful.

[rozyczko]

A while ago we created something similar for SasView

https://confluence.ess.eu/spaces/DAM/pages/88834326/SasView+Coding+Rules

Some of this text can still be lifted over and reused for EasyScience

[rozyczko]

These were created with Python 2.x and PyQt in mind, so many aspects are obsolete or just plain wrong.

[AndrewSazonov]

I also think this is a really good idea. Having shared development guidelines should definitely help improve both quality and consistency across the projects.

I do have a few questions and suggestions, mostly around clarification and how this is meant to be used in practice.

First, about where this should live. Is the idea to keep these guidelines in a single place (e.g. a file in an organisation-level repo) and link to it from each project’s README.md? Should this be an extension of CONTRIBUTING.md, or a separate document?

The guidelines themselves look nice, but some points feel a bit abstract and could benefit from more concrete explanations. For example:

• “Small changes that compile and pass tests” - how small is “small”? Is there any rough guideline or expectation here?
• “Learning from existing code” - does this mean studying similar implementations in the same repo, across EasyScience projects, or elsewhere?
• “Test-driven when possible – Never disable tests, fix them” - do you mean actual test-driven development (i.e. writing tests before the implementation), or mainly that existing tests should always be fixed rather than disabled when they fail?
• “Include context for debugging” - what kind of context are you aiming for?
• “Handle errors at appropriate level” - could you clarify what “appropriate” means in practice?
• “Find similar features/components” - is the goal reuse, refactoring toward a shared base, or simply consistency?
• “Don’t introduce new tools without strong justification” - what would count as “strong” justification?
• “Commit code that doesn’t compile” - do you mean code that fails linting, formatting, or tests?
• “Commit working code incrementally” - this seems related to “small changes”; again, some concrete guidance would help.
• “Update plan documentation as you go” - are you talking about a roadmap, ADRs, issues, or something else?
• “Learn from existing implementations” - EasyScience projects, DMSC projects, third-party projects?
• “Stop after 3 failed attempts and reassess” - reassess how? Try a different approach, ask for feedback, discuss in the group?

Overall, I think it would be great to add a bit more detail to each item to make them as unambiguous as possible. Even better would be concrete examples - both good and bad. As Henrik mentioned earlier, having practical rules like “PR's no longer than...” would also help.

One more thought: having guidelines is important, but the hardest part is actually following them. Without some form of enforcement, they can easily be ignored. Some of the points, especially around tooling and code style, can be enforced automatically. For example, many expectations can be encoded directly in Ruff rules and pyproject.toml (as we already do to some extent). It’s one thing to say “avoid complex code”, but it’s much clearer when Ruff tells you the cyclomatic complexity is above the allowed threshold.

Pre-commit and pre-push hooks also help a lot here: only allow commits that pass linting/formatting, and only allow pushes that pass tests. This makes the expectations more explicit.

If expectations are enforced this way, we may not need to mention every low-level rule in the guidelines beyond pointing people to things like “Use the project’s formatter/linter settings” or “Refer to linter configurations and pyproject.toml” (as already suggested). For instance, something like “Text files should end with an empty line” is better enforced by tooling than written as a guideline.