NYCPHP Meetup

[David Krings]

On 1/23/2012 1:17 PM, Gary Mort wrote:
> One thing that has annoyed me more and more over time is the way books and
> classes go about teaching /how/ to program in a language.
>
> They all start off with "Hello World" and then progress slowly form there to
> more and more complicated things. I've noticed that even Ruby books, the
> poster child for unit testing, proceed in this manner.
>
> In short, they wait until /after/ someone has developed bad habits and then
> introduce version control and unit testing as an afterthought.
[...] as well as other posts...

Hi!

Here are my 2 cents on this, from the perspective of a QA analyst who writes 
code as hobby and to know just enough about it to disable the 'cannot be done 
in programming language XYZ' argument of developers.
First of all, congratulations that you want to write a course. It will be a 
lot of work, thrice as much as you think it will be. I've been there and in 
the end it will be worth the effort. Yes, please, focus on all these things 
that are not about learning more code words. There are already excellent books 
for that (and many crappy ones), but I haven't seen one that explains the 
mindset of a good developer. I do assume you target that at people who are 
learning how to code, or better to say who want to learn how to run a 
successful software project. If that is true, then no bit of code is trivial. 
Even Hello World is not trivial. In short, for anyone new to this, nothing is 
trivial. So if you want this to be a well liked course don't use words like 
"trivial". You may find it trivial, but for others it is a tremendously tricky 
problem to wrap their mind around. If you write for experienced software 
architects, then fine, mock the n00bs, but even then it is unnecessary. Don't 
even think that any of this is trivial.

- unit testing
Very important and that unit should consist of two parts: why do it and how to 
do it/what does a test need to cover. The why part should be easy for you as 
you are already fully convinced. Imagine you need to consume code from someone 
who does not write a single unit test and claims he does not have to, because 
he is a programmer for 40 years. Argue against a case like that.
What it needs to cover should be about testing edge conditions, proper error 
handling, short anything that it is not normal. At that point it may be 
helpful to see some code examples on how it is done right (please, don't 
include incorrect code or bad examples, reserve that for exercises if you want 
to add some).

- source control
In that section I wouldn't focus solely on git. In the next place subversion 
is used and others may use CVS or TFS or Vault or whatever. Focus on the 
benefits of source and version control for anything about the project (which 
includes help, documentation, etc - yes, the help and doc sources are sources 
and belong in source control) versus simply copying files to a floppy as 
backup. Still, should mention that making simple file backups is important as 
well, same as backing up the entire repository. If you want to include 
specific commands, add a table at the end that lists the basic commands for 
the most popular open source and proprietary source control systems.

- algorithms / objects / classes
Wow! Big words, big enough to scare anyone. I've come across plenty of code 
that was presented as awesome because it is "fully object oriented". I 
couldn't tell if it was or not, because it didn't work at all. The only time I 
ever used an object so far is to handle a ZIP archive, because the PHP module 
doesn't work any different. You can do plenty of stuff without creating a 
single object. I use arrays to store data and then write code around it. And 
that may just be the lead-in to show that packaging that all into an object is 
the way to go: one part are the data structures, the other part is the code 
around it. Introduce it in that manner, that way even a novice PHP coder like 
me can follow that path. Explain it without ever using the word "object", 
focus solely on the benefits and mention the disadvantages. Tell people that 
all that is called "object" in the last sentence of the section.
Same applies for algorithms. Even when you start off with a definition of the 
word it will not mean much. Talk about how to sort stuff quickly, how to find 
stuff quickly, how to arrange stuff based on a pattern. Using key words like 
that make it much easier to grasp what it is about. And again, the last 
sentence can explain that all this is known as algorithms.
And same applies for classes

- documentation
Your course needs to cover that. Fact is that we do not communicate with it 
each other in PHP (or C or Java or whatever). So something like 
"self-explaining code" is total bupkis. No matter how well structured the code 
is, I still have no clue what it does when looking at it. Documentation is 
utterly important unless you write some one time use glue code or engage in 
gogglelistic projects with a life span of less than six months. It not only 
matters which docs to write, but also when to write them. Here is how I see it:
- scope doc of project: what is it supposed to be (address label creator or a 
bird bath?)
- functional requirements: detailed list of individual features and functions 
explaining the expectations of the stakeholders (users, QA, devs, etc.)
- technical spec I: flow charts, description of approach
=> now write code, unit tests, and so on
- technical spec II: amend the first version and add a description of what was 
done, no code is to be found in here

The scope doc can be skipped if not needed and rolled into the functional 
requirements. All these docs do not need to be novels. Defining the scope in 
one or two sentences is fine, requirements can be a collection of lists with 
key words (name of a text field, max length, any chars that need to be 
rejected) plus a mockup of the UI if there is one. If there is none, a list of 
the commands expected. Tech spec needs to include the database table design 
unless there is another way to easily get to that. The first part is purely 
about stating what the plan is and how the developer understands the program 
needs to work.

- quality
The past decade I spent on learning about software QA and went through endless 
discussions about what is a bug. Of course, I forgot where I got that quote 
from (I'll find the source when you want to), but the best definition of "bug" 
I ever came across is this one: "A bug is anything that negatively impacts the 
user experience."
So quality is a matter of user perception, or even shorter: quality is a 
matter of the user. So if a developer wants to write quality code then never 
ever forget about the user. If a developer never met a user or talked to one, 
how can she or he know how the software gets used? I think any developer in 
any company should do at least a few days per month phone support. This isn't 
a problem for the one man shops, because it becomes more obvious in that 
constellation. Developers create software for others to use, not to get all 
jiggy about how awesome their new code is. If you think about users you get 
something like Firefox 3.6. If you only focus on having a good ol' time as 
developer then you get Firefox 9...and declining market share.
Make the users happy, which is a task that goes far beyond the app compiling 
and not crashing. Even a crash is OK if there is a useful error message.

- error handling
We all know the "Access violation at address 00000000" errors. They are 
totally useless. As are the 50k lines of error output from ASP.NET web apps. 
Any error, foreseen or not, needs to be properly handled producing humanly 
intelligible output that states at least what went wrong (and no, nobody aside 
a developer knows what access violation means), what was expected as input, 
what was received as input, and what a possible remedy could be. Also, include 
the name of the module or file in which the error occurred. That should be 
easier when distributing the code across multiple files rather than stuffing 
everything into one big file.

- adherence to UX guidelines
There are several UX guidelines published by various companies. I know that 
Apple, Microsoft and IBM published theirs. Also, the "The essential guide to 
user interface design" by W. O. Galitz is an excellent resource. Each company 
may have their own design and style guides, and if not, it is long overdue to 
craft them.


So much for now, come to think, you could write the entire course without any 
code samples and still have a very valuable product.

David