{"id":22381727,"url":"https://github.com/tristanbettany/waysofworking","last_synced_at":"2026-03-19T22:37:50.925Z","repository":{"id":51234710,"uuid":"322615878","full_name":"tristanbettany/WaysOfWorking","owner":"tristanbettany","description":"Ways of working successfully in a small development team.","archived":false,"fork":false,"pushed_at":"2023-09-06T07:26:30.000Z","size":29,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-01T01:35:15.970Z","etag":null,"topics":["agile","code-of-conduct","development","guidelines","kanban","operations","proceedures","psr","scrum","standards","team","waterfall","ways-of-working","workflow"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tristanbettany.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-18T14:21:06.000Z","updated_at":"2023-11-23T21:37:42.000Z","dependencies_parsed_at":"2024-12-05T00:10:05.682Z","dependency_job_id":"a6178859-a79d-4c57-9fcb-7e89961102a9","html_url":"https://github.com/tristanbettany/WaysOfWorking","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tristanbettany%2FWaysOfWorking","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tristanbettany%2FWaysOfWorking/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tristanbettany%2FWaysOfWorking/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tristanbettany%2FWaysOfWorking/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tristanbettany","download_url":"https://codeload.github.com/tristanbettany/WaysOfWorking/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245720840,"owners_count":20661483,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agile","code-of-conduct","development","guidelines","kanban","operations","proceedures","psr","scrum","standards","team","waterfall","ways-of-working","workflow"],"created_at":"2024-12-05T00:10:03.194Z","updated_at":"2026-01-07T00:15:42.122Z","avatar_url":"https://github.com/tristanbettany.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ways Of Working\n\nThis is a collection of ideas and advice which exists to detail the most ideal and realistic ways of working \nin a small web development team and may or may not align to your ideas. The information should be relevant irrespective\nof your chosen workflow (agile/waterfall, etc). \n\nThe purpose of this is purley because following publicly produced standards are a great idea on paper but in practise\nthey either dont work in their entirity or they dont cover anything other than code syntax, or management workflows. \nIt does not cover how the 2 are directly intertwined.\n\nSome ideas here may have the potential to be based soley on the personal opinion of the author, If you think that is the \ncase please choose to ignore it. Take from these ideas what you believe would work for you or your organisation.\n\nAlthough some of the rules below may be also fully or partially covered by widley documented standards, it is important to \nre-iterate and explain some things as the importance of some of these rules can often be overlooked, and the rule \nignored.\n\n## Coding Standards\n\n\u003e NOTE: All coding standards in this document are directed towards a **PHP development team**. A lot of the coding standards\n\u003e are not needed or make no sense in other more comprihensive languages such as C++ or C#, the section below on Proceedures \u0026 Best Practises\n\u003e can still be applied to other teams, and at least inspiration can be taken from this section for teams using other languages\n\nDevelopment Teams should ideally all be on the same page and adhear to an agreed upon list of standards that benefit both the \ndevelopment team and the business. These rules should not just blindly follow PSR rules however also integrate \nstyles that the development team like to adopt.\n\n### PSR-12 Should always be followed where possible\n\nIt is not always possible to follow PSR rules, esspecially when dealing with frameworks and extending their classes.\nFor that reason you should be required to adhear to PSR-12 in all cases unless there is a specific reason it cannot \nbe done, or there is a rule the team as a whole has chosen to ignore.\n\nhttps://www.php-fig.org/psr/psr-12/\n\n### Comment only what the code cannot say\n\nPre PHP 7.4 you really needed certain parts of your classes to have docblocks and comments, but as of PHP 7.4 \nComments and docblocks have no need in existing unless used for parsing in the same way Doctrine does.\nWith type hinting for all paramaters on methods and classes including return type hinting most information we need to\nknow is in the code. The only expection I have come across for this is `@throws`. This rule insinuates that you name\nvariables well\n\n### Scope should be restrictive where possible\n\nSometimes it is not always possible to choose the scope of methods or variables if you are extending a class from a \n3rd party or framework, however in most cases you can define the scope. When defining scope all class variables should \nbe private and have getters and setters added. Any mehods not intended to be used outside of the class should be \nprivate, unless the intent is for the class to be extended and those methods to be used from the child.\n\n### Whitespace \u0026 dead code\n\nThere should always be 1 blank line at the bottom of every file. Not all IDEs may enforce this so make sure to check \nyour IDE is configured correctly. You can also set this up in `.editorconfig`. Within methods there should not be any \nstray linebreaks that do not increase readability. For example line breaks should exist to seperate sections of control \nlogic. \n\nThere should not be any methods that exist with an empty body, or a body with just a comment.\nAny code that is no longer needed should not be commented out and commited, it should be deleted and git will maintain \nthat history.\n\n### Input should always be validated\n\nAll user input to the application should be validated. Not just for validity but also for silly mistakes that the user \nmight make such as leaving white space on the end of a dicount code (this should be trimmed).\n\n### Use of a FQCN (Fully Qualified Class Name)\n\nIn modern PHP no class should ever be reffered to with a FQCN. All namespaces should go in the use statements at the\ntop of a class.\n\n### Line Length should not exceed 120 chars\n\nLines should not exceed 120 chars long to avoid the need to scroll sideways. This can be a pain when people dont \nhave a mouse that allows sideways scrolling. \n\n### Be strict\n\nYour control logic should always be written strict so as to avoid ambiguity and introduction of bugs. As a developer\nyou should always know exactly what your logic is comparing against and never should allow the code to almost guess.\nBy that I mean DONT do the following things:\n\n```php\nif ($val) {\n    //do logic\n}\n```\n\nDoing this allows your logic to run if the value is truthy which can be a boolean true or any string or any object or\nany array. Pretty much most things that arent boolean false or null. The reason this is bad is because if something \ngoes wrong elsewhere in the application and the `$val` gets set to something you dont expect your logic still runs\neither making it seem like nothing is wrong or causing a fatal further down the line.\n\nThe same applies to the following\n\n```php\nif (!$val) {\n    //do logic\n}\n```\n\nNotice the difference is the exclimation mark. This reverses the logic to check for falsey values, so as said before\nthe same problems exist as above with the added problem of the exclimation mark is very! easy to miss when a developer \nis scanning it and can cause errors in additional logic added to the same class or control logic where the developer\ndidnt realise the logic was that way round.\n\nThe fix is to always! be strict with your checks, for example like this:\n\n```php\nif ($val === true) {\n    //do logic\n}\nif ($val === 'a string') {\n    //do logic\n}\n```\n\nThe advantage of doing this is when an error occurs you will be taken to the correct location when debugging and no doubt\nwill find it easier to work out how to fix this logic. It is also much more verbose as to what is going on in your control\nlogic.\n\n### Method Readability\n\nA method should be able to be read predominantly by scanning down, and marginally left to right. Increasing scanning\nfrom left to right decreases readability.\n\nWhen method paramaters exceed 1 they should be seperated onto multiple lines to increase readability and decrease the \npossibility of sideways scrolling. For example:\n\n```php\npublic function foo(int $bar, string $diddly, array $squat) :void\n{\n    //Some Logic\n}\n```\n\nwould become:\n\n```php\npublic function foo(\n    int $bar,\n    string $diddly,\n    array $squat\n) :void {\n    //Some Logic\n}\n```\n\nIn this case it is far easier to spot the method paramater types and to see if any paramaters are missing type hints.\n\n### Naming Conventions\n\nMethods and variables should always be named using camel case and not be ambiguous. When choosing a descriptive method \nname you must do so with care thinking of the future developer looking at your code. For example:\n\n```php\ngetCat(); //This makes sense to you, to another developer theres more than one meaning\nprivate string $cat; //This makes sense to you, to another developer theres more than one meaning\n```\n\n```php\ngetCategory(); //This is better and less ambiguous\nprivate string $category; //This is better and less ambiguous\n```\n\n99% of the time most methods will be prefixed with either get, set, or is, based on its operation. Get should be used \nfor methods that return data, set for methods that change data, and is for methods that tell you the status of existing\ndata. For example:\n\n```php\ngetName();\nsetName();\nisLive();\n```\n\nOften you come across methods which the domain logic inside them doesnt point towards a getter or a setter. Instead\nthey point more towards something like `calculateFoo()` or `processFoo()`. These sitations often cannot be avoided,\nhowever it's good to think about if the method `processPriceFromInput()` for instance could actually just be named\n`getPrice()`.\n\nAll boolean variables should ideally be prefixed with is. For example:\n\n```php\nprivate bool $isActive;\nprivate bool $isTest;\n```\n\nIn some cases you may find the necessity to prefix them with `should` or `has` or `can`, dependant on the situation.\nOften this would be the naming convention for a method that may combine the rseult of checking multiple boolean values. \n\n## Proceedures \u0026 Best Practises\n\nThere are a number of proceedures and best practises which can help improve you code quality and how you develop as a\nteam, here are some of the best the team has picked up over the years.\n\n### Boy Scouting\n\nThe boy scouting rule states that `you should always leave the campground cleaner than you found it`. This should be\nadopted by all developers to help make sure that technical debt doesnt become a huge problem.\n\nThis means that all classes you make changes to when writing new features, should have a concious effort made to\ncleanup any existing code and fix any technical debt within reason and scope of those classes. This includes changes\nto the code to make it meet company standards not previously set and stamping out bugs.\n\nAll this ensures that whenever a new feature is worked on improvments to existing code always comes along with it and\ntechnical tebt does not mount up.\n\n### Code SOLID\n\nI wont explain solid here but the gist of it can generally be summed up by saying `be aware of seperation of concerns`,\nread more about it here - https://en.wikipedia.org/wiki/SOLID\n\n### Code DRY\n\nCoding DRY means `Dont Reapeat Yourself`, which sometimes is harder said than done. This though can be accomplished\nwith the boy scouting practise which allows you to cleanup code after its done incrimentally. So here you should be\nabstracting and DRYing up code either as you go along and/or part of doing Boyscouting.\n\n### Throw Exceptions\n\nMake sure that as you are writing code you are thinking about all possible edge cases that could happen which may not\nbe something that your code should handle and make sure to throw exceptions for it. By doing so these exceptions can be\ncaught at a later point and transformed into something more friendly for the user where if the application is an API for\nexample, this leaves the consumer of the API in a position where they are to handle it and avoid hitting that exception.\nEffectivley pushing that problem onto them and not you.\n\nThe more exceptions you throw on edge cases can also help in debugging too.\n\n### Catch \u0026 Log\n\nParticularly when making external requests consuming APIs or running jobs, make sure you are dropping in logs if an\nexception is thrown. Should the company you work for have a plan wth a log management service such as Rollbar you will\nbe able to easily see these errors and be alerted of problems. This will make debugging much much easier.\n\n### Commit only working code\n\nThe git tree should be traversable back in time without the codebase running into fatal exceptions due to incomplete \nfeatures. When commiting code, think about how you break up the commits, sometimes commiting file by file or even chuck\nby chunk to create a git tree that flows nicley. Should you need to commit broken code to allow a fellow developer to\nhelp debug with you, prefix the commit with `WIP:`, `[WIP]`, or `WIP -` and once solved, swiftly commit again the solution \nto that issue alone.\n\n### Aiming for high Code Coverage by testing all edge cases\n\nAll code created should have testing done using PHPUnit. When creating an API, you will need integration tests for each\nendpoint, including unit tests for the individual sections of code. When consuming APIs you will need to either stub \nthe API endpoints your using or get hold of a sandboxing environment for that API which you can use in local.\n\nYou should be hitting as many edge cases in testing as possible both happy and unhappy paths. Your tests should be\nstructured in that 1 feature or unit is tested per file with multiple scenarios in the file as seperate test methods.\n\nFor example it is not recommended to have and `OrderTest` file which has mutiple test scenarios that create, add, edit.\nYou should infact have a `CreateOrderTest` which has multiple scenarios for creating a test correctly and incorrectly.\n\n### Automate proceedures with CLI commands\n\nWhen developing a new feature it is a good idea to add certain aspects of that feature as CLI commands. Sometimes you \nmay recieve requests from the business to perform these tasks once the application is live, and you'll be pleased\nyou made those commands then.\n\n### Pair coding\n\nPair coding is not or everyone and doesnt work in all teams. It can sometimes require a strong bond and similar\nworking style between 2 developers. When this rare situation is found it should be encouraged for solving complex \nissues and debugging difficult mystical problems. THe power of 2 minds working together can be far better than 1 mind\ngoing round and round in circles.\n\n### Plan your design and architechture\n\nA well planned architechture for an application is much better than unplanned. There is no shame in spending the \nfirst few days of developing a new feature or application, thinking through ideas, architechture and prototyping. \nJumping straight into creating a new feature or application will inevitably have you coding yourself into a corner and \nyou will need to spend time refactoring aspects as you move further into the feature/s. Planning it all out to start with\navoids that, even if this means getting a pen to paper and drawing some ERD's.\n\nUse the right tool for the right job, do not use tools just because it is new and on trend as that can lead to\ntechnical debt and/or security issues in the future. Make sure to use design patterns when they are needed to solve a \nproblem, and don't use the business you work for as a testing ground for new un-proven design patterns that may not \nsolve your problem.\n\n## Git Flow\n\nGit Flow should be used where acceptable to improve collaboration on projects in the team and make deployments\neasier to manage.\n\nMore details on Git flow can be found here - https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow\n\n## Git Commits\n\nThe following outlines some guidelines of how to break up commits and write git commit messages that may possibly end up \nhelping you in the future.\n\n - Commits should always be small and attempt to contain code that performs only 1 job (Seperation of concerns). This will \n help in the future when you may need to cherry pick small portions of code from one branch to another.\n - Commits should never contain broken code unless you absolutely have to. See the section above https://github.com/tristanbettany/WaysOfWorking#commit-only-working-code\n - All commit messages should be clear and concise with no ambiguity\n - A commit message subject should always contain enough context to understand the actions of the developer and the impact \n of the code contained in the commit, for more detail use the commit message body.\n - A commit message subject should not contain the word `and`, when it is used it may signify you need a seperate commit. This rule should\n not take precidence over the rule of never commiting broken code, in that case usage of the word `and` is fine.\n - A commit message subject must attempt where possible to finish the scentance of `It`, `It will`, or `It has`. When choosing 1 of the 3 to complete for your work,\n try to maintain consistancy. Examples can be seen below where highlighted text would become the commit message subject.\n    - It `Fixes my problem`\n    - It will `Fix my problem`\n    - It has `Fixed my problem`\n    - It `Adds a new feature`\n    - It will `Add a new feature`\n    - It has `Added a new feature`\n    - It `Updates my existing feature`\n    - It will `Update my existing feature`\n    - It has `Updated my existing feature`\n - Commit message subjects should never be finished with a period\n - A commit message subject should not exceed 50 chars\n - All lines of a commit message body should be wrapped at 72 chars\n - A commit message body must be seperated from the commit message subject by a single blank line\n - Commits should be written in sentence case, see details here - https://en.wikipedia.org/wiki/Letter_case#Sentence_case\n - If using JIRA for project management, it is ideal to prefix all commit message subjects in square brackets with the ticket number `[CLC-123]`. \n This will provide a link to the ticket in JIRA directly from the commit.\n - When making commits which make changes from feedback on a PR/MR, make sure to commit each change independently following the rules outlined here,\n do not group into a single commit called \"PR Feedback\" for example as this is not useful to the git history and anyone navigating the git log. \n - All commit messages should have no passive agressive context towards other developers or situations in the company.\n - Commits should never be made directly to master or develop, oh and dont force push ever!\n\n \u003e *TIP*: set up a default commit message template in your git config to help you adhear to all these rules\n\n## Pull Requests\n\nA development team generally leans heavily on pull requests to assure code quality and to make sure that work is done \non time. Lets see the best way PR's can be managed to keep all the cogs moving.\n\n### Submitting\n\nWhen submitting a pull request the last thing a developer reviewing it wants is to come to review it and find that the \nbranch is out of date with the target branch and the description is lacking details of what you have done.\n\nMake sure that you are keeping your PRs up to date with the target branch, until they have been reviewed. To do this \nyou can do the following:\n\n```\ngit fetch\ngit checkout your-branch-in-for-pr\ngit merge --no-ff origin/target-branch\n```\n\nWhen it comes to a description, its all very well and good linking to a ticket that was the request for the new feature,\nhowever this could be and generally will be a rather high level description of the request. It's your responsability to\ndescribe the technical implimentation you chose and the reasons behind it. Maybe some limitations as to why you didnt choose\nan obvious one and went with something more complex. You should also think about any special requirements for testing\nand will the reviewer need to know this. Also for an audit trail its wise to include a screenshot for any visual changes\nyou made.\n\n### Reviewing \u0026 Commenting\n\nTo make sure to keep on top of PR's it is advisable to reserve 30 mins at the end of each day to review them.\nEach PR should be reviewed for coding standards, syntx issues, and of course domain/business logic. \n\nCommenting on PR's can be tricky, too often developers can comment on PRs with little thought or concern for the person \nrecieving the comment. If the developer has spent alot of time working on it, some comments can feel quite grating and \ncan be taken to heart. Due to this, always make sure to do your best to convey tone of voice in a PR comment using emojis,\nand if you are trying to explain something particularly complex maybe even follow up the comment with a message on Teams/Slack/Discord etc.\n\nSometimes you may notice a mistake has been made in a PR which may have simply been an oversight and could potentially be\nslightly embaresing to mention publicly in PR comments. This can sometimes then be best to contact the developer directly via\nTeams to let them know some improvements they can make before you do an official review.\n\nAll of this helps avoid any confict and toxic situations in comments sections of PRs.\n\n### Approval \u0026 Merging\n\nThis section of PRs should be fairly simple. It is recommended that when there are at least 2 (or the amount the business is happy with) \napprovals from reviewers which should come from a collection of developers picked by the company.\n\nSenior developers should then be able to merge it once these requirements have been met. If an update to that PR is made after the approvals quota\nis reached then the quota is reset and the approval process restarts before a merge can be completed.\n\nYou should always merge in a way that maintains the hillocks in the git tree, and remove the branch after merging.\nYou can do this like so:\n\n```\ngit checkout target-branch\ngit merge --no-ff branch-to-merge\ngit branch -D branch-to-merge\n```\n\n## Code of Conduct\n\n- Generally be good to one another, and don't take life too seriously. \n- Have time for your fellow developer and they will have time for you.\n- Respect other developers opinions and they may respect yours.\n- Remember that there is always someone out there you can learn from irregardless of yours or their level.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftristanbettany%2Fwaysofworking","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftristanbettany%2Fwaysofworking","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftristanbettany%2Fwaysofworking/lists"}