12 ms·

Best practices in modern web projects

153 points by arvida 12y ago

AlexMuir 12y ago
No idea how this is getting so many points. There's absolutely nothing of any practical interest here. Use version control and documentation... End of post. I'd say these are more industry standard practices than leading edge.
- ricardolopes 12y ago
  I have to agree. Interesting topic, but not a lot of new content there.
- romanovcode 12y ago
  >First of all, use git for version control. It is modern, works great and the majority of developers are either comfortable in using it or want to start using it. Not to mention those points were mainly subjective. Don't get me wrong, I like and use Git myself but statements like "Use this, most people use it so you must use it too!" are just horrible.
- Isamu 12y ago
  >No idea how this is getting so many points. Because the basics have to be pointed out again ... and again. I think the upvotes don't primarily mean "omg I never thought to do this" but rather "will someone please staple this to the foreheads of all the clueless devs I've had to clean up after."
- opendais 12y ago
  I upvoted it on the odd hope that one of my coworkers sees it and actually considers following some of it. ;)
- btrombley 12y ago
  It's best practices, not new practices, and a very clear concise write up at that. I wish if read this 6 months ago, rather than learning it the hard way.
- pietro 12y ago
  > I'd say these are more industry standard practices than leading edge. Yeah, that's sort of what "best practices" are all about. They are for teaching outsiders what insiders have learned through practice. The intended audience is everyone who doesn't already know this. If you consider the article of no practical interest for a seasoned insider, that's about the highest praise you can give.
- euphemize 12y ago
  True, although you'd be surprised to see how many people fail to provide proper docs, or use git for source control, still in 2014. I agree with others in here, maybe the title is just misleading more than anything else.
  - gnaritas 12y ago
    Failing to use git as your source control mechanism is not an actual problem; failing to use any source control is a problem, you don't have to use git.
- joshdotsmith 12y ago
  There will always be a new freshman class. Every year, someone joins HN (or the community at large) knowing next to nothing. We should welcome those people, not make them feel bad for being new.
  - noblethrasher 12y ago
    Yep. HN wants to avoid eternal Septembers; occasional Septembers are fine though.
ericcholis 12y ago
All of this really covers the primary thing I preach when working with new devs. "You shouldn't be the only one who knows how to set this up and run it." One thing that might be missing is good code documentation. Using DocBlock for PHP, for example. Ideally this is maintained in code, but that can get bloaty. At the very least, a git repo of markdown files. Even the built-in github wikis would suffice.
parham 12y ago
These aren't really best practices, they're too abstract. Best practices would be exactly how you do said practices the best way possible. A more appropriate title could be "list of must read articles for modern web development".
- csbrooks 12y ago
  I'm not sure about that; I feel like I got a lot from the article without following the links.
  - deleted 12y ago
    [deleted]
  - parham 12y ago
    This didn't cover anything useful it just said what everyone was already aware of, the only useful part was the links. Everything else was like saying to spread butter on toast use a butter knife.
    - timc3 12y ago
      I would be surprised how many people don't use a butter knife ;-) But I agree - way to abstract.
    - Lockyy 12y ago
      >just said what everyone was already aware of What you mean is it just said what you were already aware of. Not everyone does know all of these things, a list of things with generalised statements along with links to more detailed information is incredibly useful to someone who is just getting into the field, which I guess is exactly who this article is aimed at.
collyw 12y ago
"Git First of all, use git for version control. It is modern, works great and the majority of developers are either comfortable in using it or want to start using it. Its a pain in the arse to learn, overcomplicated for 90% of the cases it is used in. How many people actually need a distributed version control." (I use Git. It is powerful and useful, but the justification for using it in the article isn't really great. No mention of Mercurial or other version control systems).
- Expez 12y ago
  The benefit of standardizing on a tool that is "good enough" is worth it imo. Learning git is easier than learning svn, darcs, hg, perforce and git and juggling between them when you want to submit patches to open source projects or get new clients.
  - couchand 12y ago
    Don't forget bzr!
    - cwyers 12y ago
      Why not?
  - collyw 12y ago
    I am not going to argue with you on that point, because that is the reason I am using GIT. CVS would be far more suited to my personal use cases.
    - eropple 12y ago
      I'm curious how CVS is suited enough to anyone's use cases to be worth discussing when SVN exists.
- couchand 12y ago
  The world's inconsistent internet connections are a great reason to require distributed version control. I'm often trying to work from a location without a reliable connection to the internet, be it a plane, train or bus, a coffee shop with spotty internet or a meetup. Requiring a connection to a server kills productivity in those situations. Perhaps there is something to be said for Mercurial, but unless you were previously on Subversion it's certainly not that it's easy to learn.
Demiurge 12y ago
>Serve these through a CDN that is optimised for serving static files to ensure high transfer speeds and therefore increased user happiness. I was not aware this was that common or even considered always the best practice. Is this really the best practice for any website? How exactly is a CDN more optimized than nginx on a dedicated server with 1GB connection?
- regularjack 12y ago
  One of the reasons is that CDNs are geographically distributed so the files will be served from a datacenter closer to the client.
- vukers 12y ago
  At a minimum, a CDN automatically caches and serves content from multiple servers globally.
  - Demiurge 12y ago
    Is it worth it if you have a US specific website that doesn't get that many users (~3 sessions at once)? Also, another website I administer has a lot of user uploaded content that's constantly changing. I've not dealt with a CDN before, so I don't know how CDN helps with that? I think only a fraction of the data is static in this case. PS Why the hell would someone downmod my honest question?
    - numbsafari 12y ago
      Not sure about the down mod, but I think the point of the OP is to address projects that have the goal of driving a "startup" business. In addition, with mobile, getting rid of any network latency you can is going to help. In general, though, I think you are right to ask the fundamental question. That said, it's something a lot of people end up needing anyway and it helps if you design for it up front. tl;dr - If you're building a low-volume site, the OP probably doesn't apply to you.
      - 12y ago
deleted 12y ago
[deleted]
Nexialist 12y ago
The "12 Factor App" manifesto http://12factor.net/ http://12factor.net/ is in the same vein as this, perhaps a bit more in-depth. I like the idea of these guides generally. I think it'd be more valuable if they linked to example production code that followed the principles however, since there's no substitute for the real thing. Come to think of it, I've never seen anybody write up any kind of index of (for example) Github projects that exemplify good design patterns for people to look at. Or some kind of recommended code reference list.
- pmichaud 12y ago
  I like that idea too, but I suspect that there are pretty much zero non-trivial projects that actually follow best practices like these consistently. Maybe I'm wrong.
IgorPartola 12y ago
Ugh. Pull requests again? OK, look, unless your team is so large that you can't effectively communicate otherwise, pull requests are just friction. Use feature branches, then merge them when they are ready. Trying to pretend like your two person team is a huge open source project with many distributed part-time and full-time developers is cargo cult at its worst.
- eropple 12y ago
  While I'm often lazy about this, I think that there are advantages to doing this with this once your team is over just a solo developer. Encouraging your fellow developers to read (and at least understand, if not internalize) your code has some bus-proofing to it, and I don't think it's that much friction if done well.
  - dllthomas 12y ago
    And helps make sure people are familiar with more of the code.
- awj 12y ago
  Meh, it doesn't have to be friction. If the goal is to ensure your other team member sees the changes you're making before they're merged in a pull request both accomplishes that and gives you both a place to put some notes related to that process. I think you're ascribing too much ceremony to this. It's useful to have something written down for any discussion about these changes, and a pull request is as good of a place as any for that. Plus it ensures everything is all set up to merge once you're both satisfied with the changes.
- hoggle 12y ago
  We are a trusting team and don't do pull requests with our closed source repos either. To avert chaos it's much better to have an orderly branching model in place e.g. feature branches! My fellow partners made us go all "git flow" last year and the result has been a really tidy and satisfying workflow: http://nvie.com/posts/a-successful-git-branching-model/ http://nvie.com/posts/a-successful-git-branching-model/ Atlassian's SourceTree also helps us with maintaining "the flow": http://www.sourcetreeapp.com http://www.sourcetreeapp.com https://www.atlassian.com/git/workflows https://www.atlassian.com/git/workflows Git extensions and screencast on how to setup on OSX: https://github.com/nvie/gitflow https://github.com/nvie/gitflow http://build-podcast.com/git-flow/ http://build-podcast.com/git-flow/
st3fan 12y ago
I am sad that this article does not contain the word 'Security'.
kylequest 12y ago
I wouldn't call the part about configurations (in the post and in the 12 factor app reference) a best practice. Using environment variables is a hack that has negative side effects including security side effects. This statement is just silly: "A good goal is that the application can be open sourced at any time without compromising any credentials." It's silly because the use of environment variables doesn't prevent anybody from putting them in a shell script that gets committed to git...
- njharman 12y ago
  You're reversing the "goal" and "practice". It's not that Environment Vars allow you to "open source / credentials". It's (goal) "be able to open source any time without compromising any credentials". One method (practice), use Environment Vars. Evars being a poor choice in your and somewhat my opinion, does not translate into the goal being poor. It's a laudable goal.
  - kylequest 12y ago
    Being able to open source code without compromising any credentials is a great goal, but using environment variables doesn't really accomplish it UNLESS your code only runs on a PaaS, which will always supply all of your app's env vars, but it's unrealistic for a number of reasons. First, there'll be extra vars that your PaaS won't fully manage, so you'll have to keep track of them yourself and then later configure the PaaS environment, so your app can access them. Second, for non-PaaS applications/deployments you still need to manage the environment variables. The variables don't magically appear by themselves :-) They need to be stored somewhere... This "somewhere" is likely to be the git repo (for the app), so you are back to square one on this.
- curun1r 12y ago
  I think they made a mistake by making the "gets configuration parameters from the environment" specific to a UNIX/system environment. You can accomplish the same effect in a much more elegant manner using a tool like etcd or consul. But the important part is really that the deployable unit pulls its configuration from the environment where it's deployed. There are a ton of ways to accomplish this...environment variables are one way, etcd/consul is another, you can use something language-specific like JNDI or you can even use a file with configs in a well-known location, but you really need to be deploying the same artifact to QA, E2E testing, production and whatever other environments you might have.
owenversteeg 12y ago
I disagree with "Keep the master branch deployable at all times." Both my CSS framework Min (http://minfwk.com http://minfwk.com) and several other popular GitHub projects use the strategy of 'only use one branch, and use tags to mark stable versions'. Min's only branch (gh-pages, so we can serve the site with GitHub) is usually "unstable" (in the sense that a CSS framework can be unstable.) If someone wants a stable release, that's what Git's tag system is for.
- awj 12y ago
  I think the idea is sound, but the reasoning isn't. Keeping master deployable at all times forces breaking changes off into feature branches so unrelated pieces of functionality can't interfere with each other's release schedules. Keeping master deployable for bug fixes doesn't make sense to me, though. Are you going to deploy new features sitting in master because something else had a bug? Just go look up the last release tag, make your bug fixes there, then merge them into master. I've been bitten too many times by unstable features holding up releases on master (both my features and other team member's). Feature branches do a wonderful job of solving this and the required merge back into master gives you a nudge to prevent scope creep.
Arkadir 12y ago
Honest question: what are the benefits of using environment variables over having an actual configuration file (that is obviously not added to version control) ?
- blogimus 12y ago
  Ability to run on Heroku
- didip 12y ago
  Heroku & Docker. But most importantly, it lends to dynamic configuration when using etcd or zookeeper.
- IgorPartola 12y ago
  Unless your environment demands it, it doesn't matter. In fact, it can be a bit of a pain in the ass to implement on your own, if you are not using Heroku or some such. The main point there is to not put secrets into your git repo. How you accomplish that for the most part doesn't matter.

153 points by arvida 12y ago

No idea how this is getting so many points. There's absolutely nothing of any practical interest here. Use version control and documentation... End of post. I'd say these are more industry standard practices than leading edge.

ricardolopes 12y ago
I have to agree. Interesting topic, but not a lot of new content there.
romanovcode 12y ago
>First of all, use git for version control. It is modern, works great and the majority of developers are either comfortable in using it or want to start using it. Not to mention those points were mainly subjective. Don't get me wrong, I like and use Git myself but statements like "Use this, most people use it so you must use it too!" are just horrible.
Isamu 12y ago
>No idea how this is getting so many points. Because the basics have to be pointed out again ... and again. I think the upvotes don't primarily mean "omg I never thought to do this" but rather "will someone please staple this to the foreheads of all the clueless devs I've had to clean up after."
opendais 12y ago
I upvoted it on the odd hope that one of my coworkers sees it and actually considers following some of it. ;)
btrombley 12y ago
It's best practices, not new practices, and a very clear concise write up at that. I wish if read this 6 months ago, rather than learning it the hard way.
pietro 12y ago
> I'd say these are more industry standard practices than leading edge. Yeah, that's sort of what "best practices" are all about. They are for teaching outsiders what insiders have learned through practice. The intended audience is everyone who doesn't already know this. If you consider the article of no practical interest for a seasoned insider, that's about the highest praise you can give.
euphemize 12y ago
True, although you'd be surprised to see how many people fail to provide proper docs, or use git for source control, still in 2014. I agree with others in here, maybe the title is just misleading more than anything else.
- gnaritas 12y ago
  Failing to use git as your source control mechanism is not an actual problem; failing to use any source control is a problem, you don't have to use git.
joshdotsmith 12y ago
There will always be a new freshman class. Every year, someone joins HN (or the community at large) knowing next to nothing. We should welcome those people, not make them feel bad for being new.
- noblethrasher 12y ago
  Yep. HN wants to avoid eternal Septembers; occasional Septembers are fine though.

ericcholis 12y ago

All of this really covers the primary thing I preach when working with new devs. "You shouldn't be the only one who knows how to set this up and run it." One thing that might be missing is good code documentation. Using DocBlock for PHP, for example. Ideally this is maintained in code, but that can get bloaty. At the very least, a git repo of markdown files. Even the built-in github wikis would suffice.

parham 12y ago

These aren't really best practices, they're too abstract. Best practices would be exactly how you do said practices the best way possible. A more appropriate title could be "list of must read articles for modern web development".

csbrooks 12y ago
I'm not sure about that; I feel like I got a lot from the article without following the links.
- deleted 12y ago
  [deleted]
- parham 12y ago
  This didn't cover anything useful it just said what everyone was already aware of, the only useful part was the links. Everything else was like saying to spread butter on toast use a butter knife.
  - timc3 12y ago
    I would be surprised how many people don't use a butter knife ;-) But I agree - way to abstract.
  - Lockyy 12y ago
    >just said what everyone was already aware of What you mean is it just said what you were already aware of. Not everyone does know all of these things, a list of things with generalised statements along with links to more detailed information is incredibly useful to someone who is just getting into the field, which I guess is exactly who this article is aimed at.

collyw 12y ago

"Git First of all, use git for version control. It is modern, works great and the majority of developers are either comfortable in using it or want to start using it. Its a pain in the arse to learn, overcomplicated for 90% of the cases it is used in. How many people actually need a distributed version control." (I use Git. It is powerful and useful, but the justification for using it in the article isn't really great. No mention of Mercurial or other version control systems).

Expez 12y ago
The benefit of standardizing on a tool that is "good enough" is worth it imo. Learning git is easier than learning svn, darcs, hg, perforce and git and juggling between them when you want to submit patches to open source projects or get new clients.
- couchand 12y ago
  Don't forget bzr!
  - cwyers 12y ago
    Why not?
- collyw 12y ago
  I am not going to argue with you on that point, because that is the reason I am using GIT. CVS would be far more suited to my personal use cases.
  - eropple 12y ago
    I'm curious how CVS is suited enough to anyone's use cases to be worth discussing when SVN exists.
couchand 12y ago
The world's inconsistent internet connections are a great reason to require distributed version control. I'm often trying to work from a location without a reliable connection to the internet, be it a plane, train or bus, a coffee shop with spotty internet or a meetup. Requiring a connection to a server kills productivity in those situations. Perhaps there is something to be said for Mercurial, but unless you were previously on Subversion it's certainly not that it's easy to learn.

Demiurge 12y ago

>Serve these through a CDN that is optimised for serving static files to ensure high transfer speeds and therefore increased user happiness. I was not aware this was that common or even considered always the best practice. Is this really the best practice for any website? How exactly is a CDN more optimized than nginx on a dedicated server with 1GB connection?

regularjack 12y ago
One of the reasons is that CDNs are geographically distributed so the files will be served from a datacenter closer to the client.
vukers 12y ago
At a minimum, a CDN automatically caches and serves content from multiple servers globally.
- Demiurge 12y ago
  Is it worth it if you have a US specific website that doesn't get that many users (~3 sessions at once)? Also, another website I administer has a lot of user uploaded content that's constantly changing. I've not dealt with a CDN before, so I don't know how CDN helps with that? I think only a fraction of the data is static in this case. PS Why the hell would someone downmod my honest question?
  - numbsafari 12y ago
    Not sure about the down mod, but I think the point of the OP is to address projects that have the goal of driving a "startup" business. In addition, with mobile, getting rid of any network latency you can is going to help. In general, though, I think you are right to ask the fundamental question. That said, it's something a lot of people end up needing anyway and it helps if you design for it up front. tl;dr - If you're building a low-volume site, the OP probably doesn't apply to you.
    - 12y ago

deleted 12y ago

[deleted]

Nexialist 12y ago

The "12 Factor App" manifesto http://12factor.net/ http://12factor.net/ is in the same vein as this, perhaps a bit more in-depth. I like the idea of these guides generally. I think it'd be more valuable if they linked to example production code that followed the principles however, since there's no substitute for the real thing. Come to think of it, I've never seen anybody write up any kind of index of (for example) Github projects that exemplify good design patterns for people to look at. Or some kind of recommended code reference list.

pmichaud 12y ago
I like that idea too, but I suspect that there are pretty much zero non-trivial projects that actually follow best practices like these consistently. Maybe I'm wrong.

IgorPartola 12y ago

Ugh. Pull requests again? OK, look, unless your team is so large that you can't effectively communicate otherwise, pull requests are just friction. Use feature branches, then merge them when they are ready. Trying to pretend like your two person team is a huge open source project with many distributed part-time and full-time developers is cargo cult at its worst.

eropple 12y ago
While I'm often lazy about this, I think that there are advantages to doing this with this once your team is over just a solo developer. Encouraging your fellow developers to read (and at least understand, if not internalize) your code has some bus-proofing to it, and I don't think it's that much friction if done well.
- dllthomas 12y ago
  And helps make sure people are familiar with more of the code.
awj 12y ago
Meh, it doesn't have to be friction. If the goal is to ensure your other team member sees the changes you're making before they're merged in a pull request both accomplishes that and gives you both a place to put some notes related to that process. I think you're ascribing too much ceremony to this. It's useful to have something written down for any discussion about these changes, and a pull request is as good of a place as any for that. Plus it ensures everything is all set up to merge once you're both satisfied with the changes.
hoggle 12y ago
We are a trusting team and don't do pull requests with our closed source repos either. To avert chaos it's much better to have an orderly branching model in place e.g. feature branches! My fellow partners made us go all "git flow" last year and the result has been a really tidy and satisfying workflow: http://nvie.com/posts/a-successful-git-branching-model/ http://nvie.com/posts/a-successful-git-branching-model/ Atlassian's SourceTree also helps us with maintaining "the flow": http://www.sourcetreeapp.com http://www.sourcetreeapp.com https://www.atlassian.com/git/workflows https://www.atlassian.com/git/workflows Git extensions and screencast on how to setup on OSX: https://github.com/nvie/gitflow https://github.com/nvie/gitflow http://build-podcast.com/git-flow/ http://build-podcast.com/git-flow/

st3fan 12y ago

I am sad that this article does not contain the word 'Security'.

kylequest 12y ago

I wouldn't call the part about configurations (in the post and in the 12 factor app reference) a best practice. Using environment variables is a hack that has negative side effects including security side effects. This statement is just silly: "A good goal is that the application can be open sourced at any time without compromising any credentials." It's silly because the use of environment variables doesn't prevent anybody from putting them in a shell script that gets committed to git...

njharman 12y ago
You're reversing the "goal" and "practice". It's not that Environment Vars allow you to "open source / credentials". It's (goal) "be able to open source any time without compromising any credentials". One method (practice), use Environment Vars. Evars being a poor choice in your and somewhat my opinion, does not translate into the goal being poor. It's a laudable goal.
- kylequest 12y ago
  Being able to open source code without compromising any credentials is a great goal, but using environment variables doesn't really accomplish it UNLESS your code only runs on a PaaS, which will always supply all of your app's env vars, but it's unrealistic for a number of reasons. First, there'll be extra vars that your PaaS won't fully manage, so you'll have to keep track of them yourself and then later configure the PaaS environment, so your app can access them. Second, for non-PaaS applications/deployments you still need to manage the environment variables. The variables don't magically appear by themselves :-) They need to be stored somewhere... This "somewhere" is likely to be the git repo (for the app), so you are back to square one on this.
curun1r 12y ago
I think they made a mistake by making the "gets configuration parameters from the environment" specific to a UNIX/system environment. You can accomplish the same effect in a much more elegant manner using a tool like etcd or consul. But the important part is really that the deployable unit pulls its configuration from the environment where it's deployed. There are a ton of ways to accomplish this...environment variables are one way, etcd/consul is another, you can use something language-specific like JNDI or you can even use a file with configs in a well-known location, but you really need to be deploying the same artifact to QA, E2E testing, production and whatever other environments you might have.

owenversteeg 12y ago

I disagree with "Keep the master branch deployable at all times." Both my CSS framework Min (http://minfwk.com http://minfwk.com) and several other popular GitHub projects use the strategy of 'only use one branch, and use tags to mark stable versions'. Min's only branch (gh-pages, so we can serve the site with GitHub) is usually "unstable" (in the sense that a CSS framework can be unstable.) If someone wants a stable release, that's what Git's tag system is for.

awj 12y ago
I think the idea is sound, but the reasoning isn't. Keeping master deployable at all times forces breaking changes off into feature branches so unrelated pieces of functionality can't interfere with each other's release schedules. Keeping master deployable for bug fixes doesn't make sense to me, though. Are you going to deploy new features sitting in master because something else had a bug? Just go look up the last release tag, make your bug fixes there, then merge them into master. I've been bitten too many times by unstable features holding up releases on master (both my features and other team member's). Feature branches do a wonderful job of solving this and the required merge back into master gives you a nudge to prevent scope creep.

Arkadir 12y ago

Honest question: what are the benefits of using environment variables over having an actual configuration file (that is obviously not added to version control) ?

blogimus 12y ago
Ability to run on Heroku
didip 12y ago
Heroku & Docker. But most importantly, it lends to dynamic configuration when using etcd or zookeeper.
IgorPartola 12y ago
Unless your environment demands it, it doesn't matter. In fact, it can be a bit of a pain in the ass to implement on your own, if you are not using Heroku or some such. The main point there is to not put secrets into your git repo. How you accomplish that for the most part doesn't matter.