6 ms·
Code with Engineering Playbook
- guard0g 5y agoThanks. This applies perfectly to the current organization I consult for with their newly spun up ML team.
- iou 5y agoAs much as one could "nitpick" about ommisions or unnecessary points, for large companies these things are obvious yet necessary. I also liked the writing style guides that Microsoft and Google put out in recent years: - https://docs.microsoft.com/en-us/teamblog/style-guide https://docs.microsoft.com/en-us/teamblog/style-guide - https://developers.google.com/style/highlights https://developers.google.com/style/highlights
- rationalfaith 5y agoThanks for that! Definitely giving it a read as I want to make my writing quality more consistent.
- TeeMassive 5y agoToo bad Google is going woke https://developers.google.com/style/inclusive-documentation#ableist-language https://developers.google.com/style/inclusive-documentation#...
- daqhris 5y agoGlad you shared these valuable resources. As a self-taught coder, I always admired the quality in writings published by these big orgs but I couldn't emulate them. On the links you get access to various clear guidelines which are quite helpful for open-source technical docs and project description. Thank you Ser.
- rationalfaith 5y agoGood stuff! Always good to see how the big players do it!
- noen 5y agoThis was written by the organization I used to work for in Microsoft. It was developed over the last 6 years by the Commercial Software Engineering organization through hundreds of real, production ready, engineering engagements with Microsoft customers and partners. There’s nothing groundbreaking for seasoned engineers but it serves as a very robust set of reminders, especially the secondary and tertiary elements that often fall off when projects get stressed to move faster/cheaper/more featured. Also important that this isn’t Microsoft’s home grown process - rather an amalgamation of working with hundreds of companies - some tech companies, many not - with wide ranges of software engineering maturity. It’s also written and maintained by the engineers directly and with a singular purpose. No marketing, no fluff, no technology or vendor implementations.
- davedx 5y agoLots of good stuff in there. One that caught my eye is “able to change logging level without code changes”. I would take that one step further to “without redeploying”. Going to try and implement that in my own projects. I disagree strongly with “90%+ unit test coverage” though. Diminishing returns are very real there.
- Stampo00 5y agoI know this is meant more for backend applications than software meant to run on end user hardware, but... >able to change logging level without code changes The folks at Suckless would like a word. ;-) Personally, I think having to recompile software just to change settings is a royal pain in the butt.
- vasergen 5y agoagreed, I think this one comes from 12 factors apps methodology, see part III about config https://12factor.net https://12factor.net.
- spyremeown 5y ago>I disagree strongly with “90%+ unit test coverage” though. Diminishing returns are very real there. Hi, stupid junior here. Can you elaborate a bit or give me some reading material? I'm currently struggling to get good practices with tests and understanding associated metrics. Thank you!
- ollien 5y agoI'll take any chance to repost this: https://testing.googleblog.com/2010/07/code-coverage-goal-80-and-no-less.html https://testing.googleblog.com/2010/07/code-coverage-goal-80... That said, it's very easy to write tests that produce high code coverage, but do not test much that is useful (do they assert the things we truly need to check for?). It's also a pointless exercise to try and cover every single branch (e.g. does every defensive error check need to be asserted on?) It's a delicate balance and I'm sure some people will disagree with this, even.
- vasergen 5y agoI am working in very small company, but the funny part is - most of the points from the playbook applicable and fit well here.
- beny23 5y agoI feel a bit “we value processes over people” on this one. Not disagreeing with a lot that’s said but it just feels a bit prescriptive and I think agile (as in manifesto rather than big consultancy) is very much context specific