12 ms·

Software Engineering principles to make teams better

382 points by _wp_ 5y ago

darkrai0707 5y ago
This is a great initiative. It would be great if across each principle, we can have examples on how this principle helps to improve the code quality
- AdamCraven 5y ago
  Some principles do have this already, it depends on the princple. They tend to be more code focused, such as compute properties when possible: https://principles.dev/p/compute-properties-when-possible/ https://principles.dev/p/compute-properties-when-possible/ It would be hard to do it for every case, as principles interact together to create more complex behaviors. I'll be discussing this more in "emergent behaviors" in "principle-driven engineering" at some point. But the essence is architecture can arise from a few principles together. It's a bottom up approach to architecture where team members understand the "why" so there are shared mental models between the team.
iandanforth 5y ago
I like a lot of these principles but there is a crucial element missing from this presentation and that is time. As a company grows the importance of each of these principles changes. As a project within an established company grows a similar maturation happens. If you tried to adhere to all 'best practices' (principles or not) from day 1 of a project you'd be carrying a lot of weight that could crush otherwise good ideas. Some principles, when presented without a timeline, seem contradictory and that can lead to fights on teams where developers are well meaning but less experienced. I'm encouraged that this presentation includes dimensions along which you can slice the principles, but I encourage the authors to adopt a "stage" dimension as well that helps focus devs/learners on principles appropriate for 1. The stage they are in and 2. The immediate next stage.
- AdamCraven 5y ago
  The temporal nature of principles - It's a good suggestion. It's always hard to slice reality. Teams should come up with their own list of principles which reflect the team and adopt organizational ones that make sense. As organization ones will tend to be wider in scope and less prescriptive, it should be less of a problem to adopt them. Basically teams should decide what's right for them based on their backgrounds and the organisation should provide general direction. The principles become more useful when they are context sensitive, so principles lists are the next big feature (i.e one for your team, another for your organization) This feedback is really useful and will inform the design of the app. If you have a good idea Ian of what you think is useful, please let me know how I can help. I think I've grokked the basics of what you're saying, but it would be good to lock it down.
AdamCraven 5y ago
Oh wow, author here - I wasn't quite expecting this to appear here today. I've only really just start talking to people about it. That said, my mission is to make software engineering better for everyone. By capturing the best principles from the best in the world at what they do. And to organise and share that knowledge, freely. It's currently missing features to organise principles well, but I'm working on it (discussion here: https://github.com/PrinciplesDotDev/principles/discussions/20 https://github.com/PrinciplesDotDev/principles/discussions/2...) You can reach me through my profile or following me on @princples_dev (twitter) - I've only starting pushing this, but a lot more will be coming soon. It's an open source project and it needs your principles to make this a reality so if you've got some to share, please do. Or if you have feedback, leave it here. I'm building it for you.
- vvladymyrov 5y ago
  Is there one page where all principles and information about them are collected as one page so it can be downloaded and read in ereader?
  - AdamCraven 5y ago
    All principles on the website are currently in this repository: https://github.com/PrinciplesDotDev/principles https://github.com/PrinciplesDotDev/principles In fact, this is the database for the website. So you can download them from there and put it in an ereader or import it into an application that supports .md format.
vageli 5y ago
What does "Iterate in Thens" mean?
- AdamCraven 5y ago
  Well to quote the "what" of the principle https://principles.dev/p/iterate-in-thens/ https://principles.dev/p/iterate-in-thens/ You should iterate sequentially on a focused chunk of work at a time. Once that chunk has been completed THEN start on the next chunk of work. This is opposed to doing multiple chunks of different of work in parallel. It's really a way of working as opposed to operating on code.
- EricE 5y ago
  Click on it and find out?
CraigJPerry 5y ago
I think i’ve got a slightly different take - i’m not saying my take is any better though. If we’re talking engineering principles, not team dynamics, then it’s: 1. Use immutability by default, even in languages that make that harder than it should be 2. Understand how liberating idempotency is 3. Divide and conquer, use abstraction to make hard problems manageable 4. Delete code, delete tests, re-write stuff, re-write it again. Painful? Keep doing this till you get to the other side and feel liberation and empowerment, took me years to get past wincing at the idea of re-writing that thing AGAIN 5. Pay attention to your build tooling - to do any given task, it should always take exactly 1 command. How do i run the tests? Run the test command. How do i deploy to non-prod? Run the deploy command. Etc If we’re talking softer stuff: 1. Don’t block collaboration - e.g. if there are 5 people don’t work on 5 tasks concurrently. Work on 1, maybe 2 in some cases 2. Accomodate 2 types of work: work that needs collaboration & synchronisation (brain storming, planning, why are we even doing this, that kinda thing) work that needs focus time - sometimes that’s focus as an individual, sometimes that’s a mob focussed on one task and saying no to every other distraction in the world no matter how “urgent” 3. Change what you’re doing throughout the day, don’t try to code all day, you’ll get in a rut, you won’t write your best code after a while. You can optimise this step, e.g. if the team is low energy after lunchtime, use that to your advantage and schedule the easy boring work then, don’t be afraid to use humour or burn low energy time just getting to know each other better 4. Make sure people are being heard in the team. Hardest point to get right.
- AdamCraven 5y ago
  I really like that you've thought about these - and feel free to submit them not only will you get a founding badge but if you're the first person to create it you'll be known as the source of them in the future. It's not really about better or worse, what I've found is different people have different backgrounds and what principles they find useful is based on several things, which may be immuntable - such as strongly held values. You're never going to make me not care about aesthetics for example, as that is intrinsic to me and that will affect the principles I like and ultimately the people that I work best with. An analogy I like to think about is that people with very different principles are like two people holding a rope and pulling away from each other - you aren't going to get anywhere fast. Whereas people with similish principles, will generally go in the right direction. Sure, they'll get tangled up from time to time and you won't always want to get in exactly the same way. But there's a collaborative nature to it and you'll both improve.
sublimefire 5y ago
Give it some time and it will end up being "The 5 Pillars of the AWS Well-Architected Framework" or something similar. Someone already mentioned that "time" is absent here. Hence you cannot generalize. Each company should probably write their own principles and make it part of their identity.
- AdamCraven 5y ago
  Indeed. That is definitely the next steps to allow individuals and eventuall companies to create their own principle lists. There are no principles that make sense in every situation, there are no teams that will have the same principles. Imagine being able to have a team and then adopt those principles easily into your team? That's the goal.
chadlavi 5y ago
> Note: This visualization was designed for screens larger than 1024 x 1024 and for desktop-style interactions. You can proceed if you'd like. Why would you put in the work to warn people they'll have a bad time instead of just fixing the bad time.
- cloverich 5y ago
  Are you asking: "Why would you do less work when you could do more work?" -- not meaning to be trite I just think the answer follows directly from your question -- its much less work to say "I haven't optimized or even evaluated this for mobile" than to optimize a site for mobile, particularly if there is some important interaction you want which is easily achievable on a desktop sized screen (like drag and drop columns for instance).
- AdamCraven 5y ago
  Can you show me where that is or what visualization that is? I haven't put anything on the website intentionally, perhaps it's auto generated. The only page that I haven't purposely optimised for mobile is the editor, as you can't really create principles on your mobile.
  - dkryptr 5y ago
    Their comment is on the wrong post. I think they meant to comment on this post: https://news.ycombinator.com/item?id=27689664 https://news.ycombinator.com/item?id=27689664
    - chadlavi 5y ago
      well hell, yep. I don't understand how this comment got in the wrong thread! Thank you for pointing that out.
maerF0x0 5y ago
> Backend ... no principles found Site checks out https://imgur.com/a/orYiokW https://imgur.com/a/orYiokW
- AdamCraven 5y ago
  Haha! It won't be long until there are some there. I may take out the filters by technology choice for the time being, because there's nothing there.
titzer 5y ago
Is it just me, but is this meme version of software engineering absolutely the lowest information density achievable? Seriously. This is a heavily-involved topic, where any project might require hundreds to thousands of hours of development, and we have five second soundbytes as principles. Ugh.
- AdamCraven 5y ago
  In software engineering, the smallest behaviors interact to cause more complex ones. In most teams, it's hard to point to those small behaviors because they have become habitual and you may have forgotten what they are. Forgotten the "why". What I see in teams that don't work well, is teams don't have that guidance or don't share similar mental models to allow them to work effectively together. So you end up arguing at a higher level than the actual problem because you can't put your finger on what you believe. Principles build capability. Take Redux, it has just three core principles: https://redux.js.org/understanding/thinking-in-redux/three-principles https://redux.js.org/understanding/thinking-in-redux/three-p... and from those core principles you can almost build the whole framework. But more importantly it provides capability and confidence to people using the framework to extend if needed in a "redux" way. Instead of looking at the documentation, they know the authors intent. The "Why" That said, the site is really in it's earlist phase and the principles will be improved over time with more in depth information as more people contribute. Eventually, a voting system will be in place so the best principles will come to the top.
- EricE 5y ago
  If you have ever heard any sports announcer/commentator go on and on about "the fundamentals" - well, here you go. As he points out little things quickly add up into big things. Don't take my word for it - search out just about any interview with a successful athlete about their career and I guarantee at least some, if not a significant chunk of it will dwell on the topic of "fundamentals".
oneshoe 5y ago
I'm pretty excited about this site's potential. I am avid promoter of creating autonomous teams through principles and goals alignment (OKR). I think there were suggestions about Time being an aspect of a principle. I wonder if this would be better represented by the SDLC stages, something like this might address the "time" part that allows it to be associated with type of work being done. Just a thought. I also wonder, at the same time, if this is too burdensome for a team or individual to do. Establishing your principles, IMHO, should be the most important thing you do, if you use them to guide your behavior. I also have hope that when people establish what their individual principles (that define them) they then can ensure when they are job hunting or self reflecting on their current job that they what they are doing is aligned with who they are to ensure they will be satisfied in that role/job/company. I just bookmarked the site. Excited to see this grow.
- AdamCraven 5y ago
  Oneshoe, thank you. On the SDLC, it could work. The temporal aspect is something I need to think through in a way that's not too complicated. Getting feedback at this stage is beneficial, even if this hit HN a lot earlier than I was expecting. Establishing your own principles is burdensome, but using others is not. Having access to everyone else's principles and being able to see what other successful teams use, makes it easy to take other people's capability and add it to your own. Imagine if you could see what principles Rob Pike or <insert favorite programmer uses> or the principles behind a library, framework or a particularly productive team? This gets me excited. It gives people the building blocks to make great things. I totally agree that individual principles is extremely important. If not for the very fact that finding and being on aligned teams is an amazing experience for everyone involved. Happier, more productive teams. I would love to have an informal chat with you, you get what I'm doing and it needs people like you to for this to succeed for the community. Drop me an email if you can take me up on the offer :)
happyweasel 5y ago
1. work as a team
akhilpotla 5y ago
I think it would be interesting to read case studies of different teams, their principles, how those decisions have impacted them, benefits, drawbacks from their approach, etc. I think principles are great, but like you yourself have said, they require context. I would especially be a valuable resource for junior and mid career engineers, of which I am one.
- AdamCraven 5y ago
  I imagine teams will shared their principle lists on blog posts and put reflections there. Not all of it would appear on the principles.dev, as I think the reflective nature would be best handled elsewhere. But acknowledging pros and cons on the website is very valuable. The next big piece of work I have to do is on principle lists ( https://github.com/PrinciplesDotDev/principles/discussions/20 https://github.com/PrinciplesDotDev/principles/discussions/2...) and figuring out what features to include and where to draw the line is going to be tricky... I need to find the principles behind it, really. It's interesting that you say they would be a valuable resource for a junior and mid-career engineers. I agree, it would. What I've found is it generally attracts people who are a) leaders (in some form or other) b) care about programming deeply.
markl42 5y ago
Cool! Similar project I maintain: https://programming.protips.wiki/ https://programming.protips.wiki/
bilalq 5y ago
It'd be cool if counter-points to a principle could also be documented alongside it. Reasoning that highlights why you may not want to adopt a principle is helpful when considering it. For example, take "One single source of truth". >Data should be held in one location, duplicates of that data should be by reference only. >Why >Changes to data are always propagated to the rest of the system. >Mutations to the data need only happen in one place. >Single source of truth means no data will be out of sync or fail to be updated. >How >Only allow data writes to happen in one location. Whether that be a call to a rest API, system call or other write actions. >Don't allow data to be stored anywhere but the single source of truth. That won't work in many situations. If you need to support high throughput OLTP use-cases but also want to support advanced filtering/sorting of large datasets, you may need something like a combination of a NoSQL DB with something like ElasticSearch. Eventual consistency is something you accept as a trade-off for enabling higher levels of performance.
- AdamCraven 5y ago
  It's funny you chose that principle in particular because it does have an exception listed: https://principles.dev/p/one-single-source-of-truth/ https://principles.dev/p/one-single-source-of-truth/ > Exceptions > Highly distributed systems - Some systems rely on data consistency to be reached eventually or may never need to have accurate data. I've written about exceptions here: https://principles.dev/documentation/#exceptions-optional https://principles.dev/documentation/#exceptions-optional In general, exceptions should be quite broad and people can add these to the principles if they know of them. They can also have higher priority "contradictory principles" which override the lower priority principles in certain cases. Overlapping of principles create complex behavior so it is usually better to have a list of principles in priority order (this will be covered under emergent behavior in "principle-driven engineering") which can override the "single source of truth" principle. An example might be: Engineers will know they should use single-source of truth, but as performance should be critical (or they have a specific business rule that states something must take less than 5ms) it will override that principle. Does that answer your question or do you think it needs to be more refined than that? I wonder if making the principles editable by the team would be a useful feature, so you'd be able to add your own exceptions to them for your particular use case.
doggosphere 5y ago
I once worked at a startup which had put together a binder of documents, declaring the company's vision, values, principles, etc. They strongly suggested new hires go through it at least briefly. I don't think anyone ever did.
- AdamCraven 5y ago
  Yeah, I know what you mean. I've a few principles for that: https://principles.dev/p/documentation-should-be-close-to-the-code/ https://principles.dev/p/documentation-should-be-close-to-th... and “They Ain’t Gonna Read It” (not on the website, yet. But it is here: https://blog.nuclino.com/brown-m-ms-or-why-no-one-s-reading-the-manual https://blog.nuclino.com/brown-m-ms-or-why-no-one-s-reading-...) The trouble with the documents you've mentioned is they don't really create capability and it's really the social structure that enforces those values and principles as opposed to the documents. With engineering it's different because it provides tangible value. From a team perspective it can help you transfer mental models. Programming is an abstract activity that benefits greatly from those shared models. They build capability, help people learn rapidly, settle disagreements, bring the team together as one and are used in things like code reviews and filtering of technical decisions. People come back to them again and again - it's integrated. Then when a new member of the team comes a long, you're not going back to those discussions again and again. As an individual. One of the reasons you look back at your principles to remind why you believe something or to be more convincing. They provide value, so they keep being used. It's also part of that persons identity. It defines what they care about and helps them join teams with people who are aligned. So I agree to an extent - They Ain’t Gonna Read It... Unless it provides value.
tuxguy 5y ago
link seems to be down slashdot(hn) effect at work ?

382 points by _wp_ 5y ago

This is a great initiative. It would be great if across each principle, we can have examples on how this principle helps to improve the code quality

AdamCraven 5y ago
Some principles do have this already, it depends on the princple. They tend to be more code focused, such as compute properties when possible: https://principles.dev/p/compute-properties-when-possible/ https://principles.dev/p/compute-properties-when-possible/ It would be hard to do it for every case, as principles interact together to create more complex behaviors. I'll be discussing this more in "emergent behaviors" in "principle-driven engineering" at some point. But the essence is architecture can arise from a few principles together. It's a bottom up approach to architecture where team members understand the "why" so there are shared mental models between the team.

iandanforth 5y ago

I like a lot of these principles but there is a crucial element missing from this presentation and that is time. As a company grows the importance of each of these principles changes. As a project within an established company grows a similar maturation happens. If you tried to adhere to all 'best practices' (principles or not) from day 1 of a project you'd be carrying a lot of weight that could crush otherwise good ideas. Some principles, when presented without a timeline, seem contradictory and that can lead to fights on teams where developers are well meaning but less experienced. I'm encouraged that this presentation includes dimensions along which you can slice the principles, but I encourage the authors to adopt a "stage" dimension as well that helps focus devs/learners on principles appropriate for 1. The stage they are in and 2. The immediate next stage.

AdamCraven 5y ago
The temporal nature of principles - It's a good suggestion. It's always hard to slice reality. Teams should come up with their own list of principles which reflect the team and adopt organizational ones that make sense. As organization ones will tend to be wider in scope and less prescriptive, it should be less of a problem to adopt them. Basically teams should decide what's right for them based on their backgrounds and the organisation should provide general direction. The principles become more useful when they are context sensitive, so principles lists are the next big feature (i.e one for your team, another for your organization) This feedback is really useful and will inform the design of the app. If you have a good idea Ian of what you think is useful, please let me know how I can help. I think I've grokked the basics of what you're saying, but it would be good to lock it down.

AdamCraven 5y ago

Oh wow, author here - I wasn't quite expecting this to appear here today. I've only really just start talking to people about it. That said, my mission is to make software engineering better for everyone. By capturing the best principles from the best in the world at what they do. And to organise and share that knowledge, freely. It's currently missing features to organise principles well, but I'm working on it (discussion here: https://github.com/PrinciplesDotDev/principles/discussions/20 https://github.com/PrinciplesDotDev/principles/discussions/2...) You can reach me through my profile or following me on @princples_dev (twitter) - I've only starting pushing this, but a lot more will be coming soon. It's an open source project and it needs your principles to make this a reality so if you've got some to share, please do. Or if you have feedback, leave it here. I'm building it for you.

vvladymyrov 5y ago
Is there one page where all principles and information about them are collected as one page so it can be downloaded and read in ereader?
- AdamCraven 5y ago
  All principles on the website are currently in this repository: https://github.com/PrinciplesDotDev/principles https://github.com/PrinciplesDotDev/principles In fact, this is the database for the website. So you can download them from there and put it in an ereader or import it into an application that supports .md format.

vageli 5y ago

What does "Iterate in Thens" mean?

AdamCraven 5y ago
Well to quote the "what" of the principle https://principles.dev/p/iterate-in-thens/ https://principles.dev/p/iterate-in-thens/ You should iterate sequentially on a focused chunk of work at a time. Once that chunk has been completed THEN start on the next chunk of work. This is opposed to doing multiple chunks of different of work in parallel. It's really a way of working as opposed to operating on code.
EricE 5y ago
Click on it and find out?

CraigJPerry 5y ago

I think i’ve got a slightly different take - i’m not saying my take is any better though. If we’re talking engineering principles, not team dynamics, then it’s: 1. Use immutability by default, even in languages that make that harder than it should be 2. Understand how liberating idempotency is 3. Divide and conquer, use abstraction to make hard problems manageable 4. Delete code, delete tests, re-write stuff, re-write it again. Painful? Keep doing this till you get to the other side and feel liberation and empowerment, took me years to get past wincing at the idea of re-writing that thing AGAIN 5. Pay attention to your build tooling - to do any given task, it should always take exactly 1 command. How do i run the tests? Run the test command. How do i deploy to non-prod? Run the deploy command. Etc If we’re talking softer stuff: 1. Don’t block collaboration - e.g. if there are 5 people don’t work on 5 tasks concurrently. Work on 1, maybe 2 in some cases 2. Accomodate 2 types of work: work that needs collaboration & synchronisation (brain storming, planning, why are we even doing this, that kinda thing) work that needs focus time - sometimes that’s focus as an individual, sometimes that’s a mob focussed on one task and saying no to every other distraction in the world no matter how “urgent” 3. Change what you’re doing throughout the day, don’t try to code all day, you’ll get in a rut, you won’t write your best code after a while. You can optimise this step, e.g. if the team is low energy after lunchtime, use that to your advantage and schedule the easy boring work then, don’t be afraid to use humour or burn low energy time just getting to know each other better 4. Make sure people are being heard in the team. Hardest point to get right.

AdamCraven 5y ago
I really like that you've thought about these - and feel free to submit them not only will you get a founding badge but if you're the first person to create it you'll be known as the source of them in the future. It's not really about better or worse, what I've found is different people have different backgrounds and what principles they find useful is based on several things, which may be immuntable - such as strongly held values. You're never going to make me not care about aesthetics for example, as that is intrinsic to me and that will affect the principles I like and ultimately the people that I work best with. An analogy I like to think about is that people with very different principles are like two people holding a rope and pulling away from each other - you aren't going to get anywhere fast. Whereas people with similish principles, will generally go in the right direction. Sure, they'll get tangled up from time to time and you won't always want to get in exactly the same way. But there's a collaborative nature to it and you'll both improve.

sublimefire 5y ago

Give it some time and it will end up being "The 5 Pillars of the AWS Well-Architected Framework" or something similar. Someone already mentioned that "time" is absent here. Hence you cannot generalize. Each company should probably write their own principles and make it part of their identity.

AdamCraven 5y ago
Indeed. That is definitely the next steps to allow individuals and eventuall companies to create their own principle lists. There are no principles that make sense in every situation, there are no teams that will have the same principles. Imagine being able to have a team and then adopt those principles easily into your team? That's the goal.

chadlavi 5y ago

> Note: This visualization was designed for screens larger than 1024 x 1024 and for desktop-style interactions. You can proceed if you'd like. Why would you put in the work to warn people they'll have a bad time instead of just fixing the bad time.

cloverich 5y ago
Are you asking: "Why would you do less work when you could do more work?" -- not meaning to be trite I just think the answer follows directly from your question -- its much less work to say "I haven't optimized or even evaluated this for mobile" than to optimize a site for mobile, particularly if there is some important interaction you want which is easily achievable on a desktop sized screen (like drag and drop columns for instance).
AdamCraven 5y ago
Can you show me where that is or what visualization that is? I haven't put anything on the website intentionally, perhaps it's auto generated. The only page that I haven't purposely optimised for mobile is the editor, as you can't really create principles on your mobile.
- dkryptr 5y ago
  Their comment is on the wrong post. I think they meant to comment on this post: https://news.ycombinator.com/item?id=27689664 https://news.ycombinator.com/item?id=27689664
  - chadlavi 5y ago
    well hell, yep. I don't understand how this comment got in the wrong thread! Thank you for pointing that out.

maerF0x0 5y ago

> Backend ... no principles found Site checks out https://imgur.com/a/orYiokW https://imgur.com/a/orYiokW

AdamCraven 5y ago
Haha! It won't be long until there are some there. I may take out the filters by technology choice for the time being, because there's nothing there.

titzer 5y ago

Is it just me, but is this meme version of software engineering absolutely the lowest information density achievable? Seriously. This is a heavily-involved topic, where any project might require hundreds to thousands of hours of development, and we have five second soundbytes as principles. Ugh.

AdamCraven 5y ago
In software engineering, the smallest behaviors interact to cause more complex ones. In most teams, it's hard to point to those small behaviors because they have become habitual and you may have forgotten what they are. Forgotten the "why". What I see in teams that don't work well, is teams don't have that guidance or don't share similar mental models to allow them to work effectively together. So you end up arguing at a higher level than the actual problem because you can't put your finger on what you believe. Principles build capability. Take Redux, it has just three core principles: https://redux.js.org/understanding/thinking-in-redux/three-principles https://redux.js.org/understanding/thinking-in-redux/three-p... and from those core principles you can almost build the whole framework. But more importantly it provides capability and confidence to people using the framework to extend if needed in a "redux" way. Instead of looking at the documentation, they know the authors intent. The "Why" That said, the site is really in it's earlist phase and the principles will be improved over time with more in depth information as more people contribute. Eventually, a voting system will be in place so the best principles will come to the top.
EricE 5y ago
If you have ever heard any sports announcer/commentator go on and on about "the fundamentals" - well, here you go. As he points out little things quickly add up into big things. Don't take my word for it - search out just about any interview with a successful athlete about their career and I guarantee at least some, if not a significant chunk of it will dwell on the topic of "fundamentals".

oneshoe 5y ago

I'm pretty excited about this site's potential. I am avid promoter of creating autonomous teams through principles and goals alignment (OKR). I think there were suggestions about Time being an aspect of a principle. I wonder if this would be better represented by the SDLC stages, something like this might address the "time" part that allows it to be associated with type of work being done. Just a thought. I also wonder, at the same time, if this is too burdensome for a team or individual to do. Establishing your principles, IMHO, should be the most important thing you do, if you use them to guide your behavior. I also have hope that when people establish what their individual principles (that define them) they then can ensure when they are job hunting or self reflecting on their current job that they what they are doing is aligned with who they are to ensure they will be satisfied in that role/job/company. I just bookmarked the site. Excited to see this grow.

AdamCraven 5y ago
Oneshoe, thank you. On the SDLC, it could work. The temporal aspect is something I need to think through in a way that's not too complicated. Getting feedback at this stage is beneficial, even if this hit HN a lot earlier than I was expecting. Establishing your own principles is burdensome, but using others is not. Having access to everyone else's principles and being able to see what other successful teams use, makes it easy to take other people's capability and add it to your own. Imagine if you could see what principles Rob Pike or <insert favorite programmer uses> or the principles behind a library, framework or a particularly productive team? This gets me excited. It gives people the building blocks to make great things. I totally agree that individual principles is extremely important. If not for the very fact that finding and being on aligned teams is an amazing experience for everyone involved. Happier, more productive teams. I would love to have an informal chat with you, you get what I'm doing and it needs people like you to for this to succeed for the community. Drop me an email if you can take me up on the offer :)

happyweasel 5y ago

1. work as a team

akhilpotla 5y ago

I think it would be interesting to read case studies of different teams, their principles, how those decisions have impacted them, benefits, drawbacks from their approach, etc. I think principles are great, but like you yourself have said, they require context. I would especially be a valuable resource for junior and mid career engineers, of which I am one.

AdamCraven 5y ago
I imagine teams will shared their principle lists on blog posts and put reflections there. Not all of it would appear on the principles.dev, as I think the reflective nature would be best handled elsewhere. But acknowledging pros and cons on the website is very valuable. The next big piece of work I have to do is on principle lists ( https://github.com/PrinciplesDotDev/principles/discussions/20 https://github.com/PrinciplesDotDev/principles/discussions/2...) and figuring out what features to include and where to draw the line is going to be tricky... I need to find the principles behind it, really. It's interesting that you say they would be a valuable resource for a junior and mid-career engineers. I agree, it would. What I've found is it generally attracts people who are a) leaders (in some form or other) b) care about programming deeply.

markl42 5y ago

Cool! Similar project I maintain: https://programming.protips.wiki/ https://programming.protips.wiki/

bilalq 5y ago

It'd be cool if counter-points to a principle could also be documented alongside it. Reasoning that highlights why you may not want to adopt a principle is helpful when considering it. For example, take "One single source of truth". >Data should be held in one location, duplicates of that data should be by reference only. >Why >Changes to data are always propagated to the rest of the system. >Mutations to the data need only happen in one place. >Single source of truth means no data will be out of sync or fail to be updated. >How >Only allow data writes to happen in one location. Whether that be a call to a rest API, system call or other write actions. >Don't allow data to be stored anywhere but the single source of truth. That won't work in many situations. If you need to support high throughput OLTP use-cases but also want to support advanced filtering/sorting of large datasets, you may need something like a combination of a NoSQL DB with something like ElasticSearch. Eventual consistency is something you accept as a trade-off for enabling higher levels of performance.

AdamCraven 5y ago
It's funny you chose that principle in particular because it does have an exception listed: https://principles.dev/p/one-single-source-of-truth/ https://principles.dev/p/one-single-source-of-truth/ > Exceptions > Highly distributed systems - Some systems rely on data consistency to be reached eventually or may never need to have accurate data. I've written about exceptions here: https://principles.dev/documentation/#exceptions-optional https://principles.dev/documentation/#exceptions-optional In general, exceptions should be quite broad and people can add these to the principles if they know of them. They can also have higher priority "contradictory principles" which override the lower priority principles in certain cases. Overlapping of principles create complex behavior so it is usually better to have a list of principles in priority order (this will be covered under emergent behavior in "principle-driven engineering") which can override the "single source of truth" principle. An example might be: Engineers will know they should use single-source of truth, but as performance should be critical (or they have a specific business rule that states something must take less than 5ms) it will override that principle. Does that answer your question or do you think it needs to be more refined than that? I wonder if making the principles editable by the team would be a useful feature, so you'd be able to add your own exceptions to them for your particular use case.

doggosphere 5y ago

I once worked at a startup which had put together a binder of documents, declaring the company's vision, values, principles, etc. They strongly suggested new hires go through it at least briefly. I don't think anyone ever did.

AdamCraven 5y ago
Yeah, I know what you mean. I've a few principles for that: https://principles.dev/p/documentation-should-be-close-to-the-code/ https://principles.dev/p/documentation-should-be-close-to-th... and “They Ain’t Gonna Read It” (not on the website, yet. But it is here: https://blog.nuclino.com/brown-m-ms-or-why-no-one-s-reading-the-manual https://blog.nuclino.com/brown-m-ms-or-why-no-one-s-reading-...) The trouble with the documents you've mentioned is they don't really create capability and it's really the social structure that enforces those values and principles as opposed to the documents. With engineering it's different because it provides tangible value. From a team perspective it can help you transfer mental models. Programming is an abstract activity that benefits greatly from those shared models. They build capability, help people learn rapidly, settle disagreements, bring the team together as one and are used in things like code reviews and filtering of technical decisions. People come back to them again and again - it's integrated. Then when a new member of the team comes a long, you're not going back to those discussions again and again. As an individual. One of the reasons you look back at your principles to remind why you believe something or to be more convincing. They provide value, so they keep being used. It's also part of that persons identity. It defines what they care about and helps them join teams with people who are aligned. So I agree to an extent - They Ain’t Gonna Read It... Unless it provides value.

tuxguy 5y ago

link seems to be down slashdot(hn) effect at work ?