Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added keep it simple principle #500

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Conversation

aaronrussellHO
Copy link
Contributor

Is this pull request a content or a code change? (Please fill in the relevant section and delete the other)

Code change

I can confirm:

Accessibility considerations

or

  • This change might impact accessibility, automated aXe tests cover the impact

or

  • This change might impact accessibility and is not covered by automated aXe tests - manual testing has been performed
    (If the change might impact accessibility then please add some further information here)

Content change

I can confirm:

  • Content does not include any code or configuration changes (excluding frontmatter information)
  • Content meets the content standards
    e.g. Writing a principle and Writing a standard
  • Content is suitable to open source, i.e.:
    • Content does not relate to unreleased gov policy
    • Content does not refer to anti-fraud mechanisms
    • Content does not include sensitive business logic
  • Last updated date for content is correct

@aaronrussellHO aaronrussellHO requested a review from a team as a code owner January 8, 2025 13:45
@aaronrussellHO aaronrussellHO changed the title Added keep it simple principle initial Added keep it simple principle Jan 8, 2025
Copy link

@niveditakhoffice niveditakhoffice left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! Just few comments

## Applications and Implications

- Simple code enables better async communication, enabling pull requests to be read with ease, and to understand the intent of the actions it performs.
- Don't overthink the future of your code, to avoid premature optimisation, don't write code until it's needed. Though extendability should still considered.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Don't overthink the future of your code, to avoid premature optimisation, don't write code until it's needed. Though extendability should still considered.
- Don't overthink the future of your code, to avoid premature optimisation, don't write code until it's needed. Though extendability should still be considered.


- Simple code enables better async communication, enabling pull requests to be read with ease, and to understand the intent of the actions it performs.
- Don't overthink the future of your code, to avoid premature optimisation, don't write code until it's needed. Though extendability should still considered.
- Follow the theme and practices within a project already, to help the existing team understand more easily.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Follow the theme and practices within a project already, to help the existing team understand more easily.
- Follow current theme and practices within a project, to help the existing team understand more easily.

- Simple code enables better async communication, enabling pull requests to be read with ease, and to understand the intent of the actions it performs.
- Don't overthink the future of your code, to avoid premature optimisation, don't write code until it's needed. Though extendability should still considered.
- Follow the theme and practices within a project already, to help the existing team understand more easily.
- Third party libraries can be useful to reuse code that someone else has already written.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if this statement is clear enough.
Are we using these third party libraries in our packages? Or we use libraries for reference? Or are we encouraging copying the code?

- Follow the theme and practices within a project already, to help the existing team understand more easily.
- Third party libraries can be useful to reuse code that someone else has already written.
- Multiple lines of comments, could mean the code is too complicated to understand and should be refactored.
- Clear variable and function names helps to keep your code self documenting.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Clear variable and function names helps to keep your code self documenting.
- Following naming convention for variables and methods helps in self documenting your code

href: /principles/write-maintainable-reusable-and-evolutionary-code/
---

Keeping your code and piplines simple, makes them easier to read, self documenting and it enables incidents to be more quickly analysed and changes made.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Keeping your code and piplines simple, makes them easier to read, self documenting and it enables incidents to be more quickly analysed and changes made.
Keeping your code and pipelines simple, makes them easier to read, self documenting and it enables incidents to be more quickly analysed and changes made.

Copy link

@PaulWrightHO PaulWrightHO left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a few general content suggestions

href: /principles/write-maintainable-reusable-and-evolutionary-code/
---

Keeping your code and piplines simple, makes them easier to read, self documenting and it enables incidents to be more quickly analysed and changes made.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Keeping your code and piplines simple, makes them easier to read, self documenting and it enables incidents to be more quickly analysed and changes made.
Keeping your code and pipelines simple makes them easier to read, self-documenting and enables incidents to be analysed and resolved faster.


## Rationale

Code should be legible by a developer at any level, creating complex and hard to read code makes it more difficult to understand, work on and, ulitimately fix issues. Readbility is important, to help others understand what the code is meant to do, asking team members to explain may mean the code is too complicated. If a developer with project experience leaves the team, the code should still be understanable to be iterated on.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Code should be legible by a developer at any level, creating complex and hard to read code makes it more difficult to understand, work on and, ulitimately fix issues. Readbility is important, to help others understand what the code is meant to do, asking team members to explain may mean the code is too complicated. If a developer with project experience leaves the team, the code should still be understanable to be iterated on.
Code should be legible by a developer at any level. Creating complex and hard to read code makes it more difficult to understand, work on and ultimately fix issues.
Readability is important to help others understand what the code is meant to do. If code needs to be explained often, this may be a sign that it is too complicated and should be simplified.
If a developer with project experience leaves the team, the remaining team members should still be able to understand and maintain the codebase.


## Applications and Implications

- Simple code enables better async communication, enabling pull requests to be read with ease, and to understand the intent of the actions it performs.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Simple code enables better async communication, enabling pull requests to be read with ease, and to understand the intent of the actions it performs.
- Simple code enables better asynchronous communication, enabling pull requests to be more easily read and understood.

## Applications and Implications

- Simple code enables better async communication, enabling pull requests to be read with ease, and to understand the intent of the actions it performs.
- Don't overthink the future of your code, to avoid premature optimisation, don't write code until it's needed. Though extendability should still considered.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Don't overthink the future of your code, to avoid premature optimisation, don't write code until it's needed. Though extendability should still considered.
- To avoid premature optimisation, don't write code until it's needed, whilst considering extensibility where appropriate.


- Simple code enables better async communication, enabling pull requests to be read with ease, and to understand the intent of the actions it performs.
- Don't overthink the future of your code, to avoid premature optimisation, don't write code until it's needed. Though extendability should still considered.
- Follow the theme and practices within a project already, to help the existing team understand more easily.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Follow the theme and practices within a project already, to help the existing team understand more easily.
- Follow the theme and practices already established within a project, to help the existing team understand new code more easily.

- Don't overthink the future of your code, to avoid premature optimisation, don't write code until it's needed. Though extendability should still considered.
- Follow the theme and practices within a project already, to help the existing team understand more easily.
- Third party libraries can be useful to reuse code that someone else has already written.
- Multiple lines of comments, could mean the code is too complicated to understand and should be refactored.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Multiple lines of comments, could mean the code is too complicated to understand and should be refactored.
- Multiple lines of comments could mean the code is too complicated to understand and should be refactored.

- Follow the theme and practices within a project already, to help the existing team understand more easily.
- Third party libraries can be useful to reuse code that someone else has already written.
- Multiple lines of comments, could mean the code is too complicated to understand and should be refactored.
- Clear variable and function names helps to keep your code self documenting.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Clear variable and function names helps to keep your code self documenting.
- Clear variable and function names help to keep your code self-documenting.

- Third party libraries can be useful to reuse code that someone else has already written.
- Multiple lines of comments, could mean the code is too complicated to understand and should be refactored.
- Clear variable and function names helps to keep your code self documenting.
- Looking at whether large functions be refactored to break out key logic can help understand a functions intent, as well as enabling reusability in the future. For further details the [Write maintainable, reusable and evolutionary code priciple](/principles/write-maintainable-reusable-and-evolutionary-code/) goes into greater depth.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Looking at whether large functions be refactored to break out key logic can help understand a functions intent, as well as enabling reusability in the future. For further details the [Write maintainable, reusable and evolutionary code priciple](/principles/write-maintainable-reusable-and-evolutionary-code/) goes into greater depth.
- Refactoring large functions to break out key logic can improve readability as well as enabling reuse in the future. For further details, the [Write maintainable, reusable and evolutionary code principle](/principles/write-maintainable-reusable-and-evolutionary-code/) goes into greater depth.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants