Stop Wasting Time By Applying Clean Code Principles

A session at PHP North West 2011

Sunday 9th October, 2011

11:30am to 12:30pm (GMT)

Does: “Everything needs to be documented!” sound familiar to you? Do you like the idea?

This talk aims to make a case for the point that forcing developers to document every single piece of code will not result in good documentation. It will generate superfluous documentation and even impair the code quality!

It is really easy to write docs for bad code because short and indescribable named functions need to be explained while code that clearly communicates its intentions and actions does not.

The question discussed include points like:

  • What needs to be explained and what doesn’t?
  • Why is it a good idea to invest time into thinking about class and function names instead of documenting them?
  • What should be included in a commit message?
  • Can we get better and more meaningful documentation by writing less of it?
  • What is the gain of certain documentation concepts?

Further discussion where documentation is really needed and showing some common documentation “refactoring” patterns. By explaining ideas like “replace comment with function call” and “replace description with variable” the talk aims to save the time of every developer. Spending it once while writing the code and then saving the time of everyone involved by not making them re-read documentation that only tells them what they should already be expecting by reading the class and function names.

About the speaker

This person is speaking at this event.
Volker Dusch

I'm a magic __method(); Well, a Software Engineer @ResearchGate interested in tdd, ops, CI, (no)sql and so on. When not coding I'm an enthusiastic gamer bio from Twitter

Coverage of this session

Sign in to add slides, notes or videos to this session

Tell your friends!

When

Time 11:30am12:30pm GMT

Date Sun 9th October 2011

Short URL

lanyrd.com/skffy

Official session page

conference.phpnw.org.uk/p

View the schedule

Share

Topics

See something wrong?

Report an issue with this session