It is undeniable that there is a laissez-faire attitude among developers when it comes to code. Coming from a Java background where everything is fairly tightly defined in terms of best practices and how things should be done, PHP is almost the opposite.
This is appealing at first, as it makes learning the language easy, as well as making PHP do what you want with relative ease when compared to a .NET or Java solution.
However, a major drawback is that it soon becomes the Wild Wild West of coding, where hired guns, who just “get the job done” seem to reign supreme. Yet this is a MAJOR short-sighted view. In the end I can almost guarantee the cowboy you got to wrangle your code did so, in a fairly inconsistent manner, so sure it works great now but if your plan is to scale your application and grow your team, you will soon feel the pain.
The number of freelance, and even web-shops who launch projects without a well-defined requirements document, a good, take time to decide on standard architecture, establish through testing or even care about a coding standards are certainly few and far between.
As a result code is usually sloppy and haphazard, and in the end new developers spend a lot of time getting to grips with the code, and unorthodox system structure.
To add to that there is little to no testing done in a documented manner. Thus if it every happens you want to extend your app or try and get some Venture Capital, what quantitative data can you show potential investors? Does it scale with the current architecture and design? What were the pitfalls and bugs, as well as were they addressed and where?
One of the best ways to get standardised is to make sure you hone your development process bit-by-bit and get the developers to gradually get into good habits like documenting their code accordingly.
- New Programmers can easily join the development team.
- Debugging is no longer a myth as you try and trace errors.
- Allow for easier and more transparent re-factoring, as each aspect of the application becomes clearer.
- Present a way for non-technical users to at least get a view of what is going on.
- Improve the chances to grow your application as you can now offer concise documentation and deliver it fast to users who may want to extend your application.
Earlier I did write about the command line, bash shell scripting and why it was important for Web developers.
I still think that every dev, needs to get handy with it, and another reason is a lot of the automated documentation tools are command line based. Of course some have web-based interfaces but most are not as crisp, clear or smooth for me.
In future I think I will look at the list of documentation tools i think are pretty good, but for now I think, just getting into the groove of better documentation is a good thing.