9

My company (small, about 40 people across 3 offices) occasionally does "developer workshops" online where one of the devs hosts a presentation about some tech topic. It's not necessarily about our work, but just to help everyone improve their skills and understanding.

I've been asked to host the next one, and the topic (chosen from a list I provided) is code style and design patterns. I know those things aren't that closely related but bear with me. I have seen many places in our code base that could be improved, some which may even qualify for DailyWTF, so I want this presentation to be as effective as possible. The problem is that I just don't know exactly what to cover in one hour.

My first idea is to use our own code as an example, to drive home the point of "please actually apply this to your work." But the topic is so broad.

Some things wrong with our code (PHP) include:

  • Minimal OO. It's been improving lately, but there are still tons of global functions. It takes me a while to find things.
  • Global config (opinion I guess). You can find $GLOBALS['blah'] scattered in just about every file.
  • Inconsistent brace style. Sounds minimal, but this actually caused a syntax error to be pushed to origin five days ago, which still wasn't corrected as of yesterday.
  • Inefficient constructs. I was able to do some basic improvements that cut running time in some areas by 70%.

I want this thing to be as useful as possible, without sounding condescending to my coworkers. So what aspects of "style" should I focus on, and which design patterns might be most useful to explain?

Tesserex
  • 3,015
  • 4
  • 26
  • 27
  • 1
    This is such an open topic that it will be hard to come to any solid conclusions. I'd try to make it clear that the point of the presentation is to make your co-workers aware of the current issues, rather than to convince them to follow a particular standard. Why don't you list the points you made in your question, and give examples of why this is a bad practice and the possible consequences i.e. technical debt. Also mention tools like ReSharper and FxCop maybe. – Nobody Jan 28 '11 at 14:48

6 Answers6

8

Be extremely careful using real code in a presentation in front of the people who write this code.

At best you're going to upset your team by pointing the finger at them in front of everyone. And what you'll get instead of "You really opened my eyes" is "WTF in front of everyone ? Did you even look at your own code dumbA.."

Take real example but modify it or be sure it cannot be traced to whoever wrote it. Or take real code from people you know but also take some of YOUR old code and play humor and inside joke with these people, standup style :)

To answer your original questions : Everything that is about readibility : funtions with as few arguments as possible, OOP, long and detailed variable name and comments.

Yahel
  • 96
  • 1
  • 2
    +1 : code reviewing is a delicate operation that takes diplomacy, and discretion, and shouldn't be used for demonstration purpose by itself. – Matthieu Jan 28 '11 at 15:47
4

I am guessing that you have a bug tracking system in your organization. Pull out some of the nastiest bugs from the repository, see the fix report on why it happened (global variables gone awry, functions doing stuff they were not meant to etc) and then discuss coding styles and design patterns that could have helped avoid this problem.

It's some hard work to do this bit of research, but this is the strongest way to drive home what you are presenting does really work.

Fanatic23
  • 7,533
  • 4
  • 31
  • 56
2

"still tons of global functions".

First, get a list. Complete is ideal.

Second, partition this list into potential classes. Think about the class definitions.

During the actual presentation, pick the biggest, most obvious, most glaring, least disputable potential class that would absorb a bunch of those global functions.

As a discussion topic. You have an idea. You need to get consensus. And answer questions along the way. And help them understand why it's a single class of objects, not a bunch of random functions sharing globals.

Then, after discussing this to the point where they understand just this class and how you arrived at the contents....

Turn on the projector.

Start typing.

Fix the code. Rerun your unit tests.

Design patterns and coding style and work getting done. All in one package.

S.Lott
  • 45,264
  • 6
  • 90
  • 154
2

in 1 hour you'll be doing well to get across a bare-minimum understanding of the basics.

i suggest pick 3 things from each topic and focus on those; limit slides to 5-7 words so that people listen to you instead of reading the slides; use made-up examples (so you don't step on people's toes, as per others' suggestions); give references at the end (URLs are better than books) as an exercise for those who want to learn more; post your slides on your intranet after your presentation. (As for the braces issue, use a code formatter; that's probably not a battle worth fighting)

Suggested topics:

  • Coding Style

    • The Zen of OOP in PHP: Coding With Style!
    • 5 Reasons Why Global Functions Cause Code Cancer
    • What's in a Name? Conventions and Common Sense (or Don't Make Me Think!)

  • Design Patterns

    • Some GoF Patterns in Our Code; an Introduction
    • Patterns Are Just Tools, not Gospel
    • The Best and the Worst: Patterns and Anti-Patterns

note: global configs are sometimes hard to avoid; one easy remedy is to put all references to them in an init function

caveat: I know only enough PHP to break wordpress and perform minor web site fixes

Steven A. Lowe
  • 33,808
  • 2
  • 84
  • 151
1

About using real code in the presentation--if used, only use it for the good examples, NEVER the bad examples. For the bad, make up your own, or find it on the web. This allows your coworkers to take pride in their work and get recognition for it. It also avoids the scenario where they may be angered/embarassed for being singled out as a bad developer.

Sparky
  • 3,055
  • 18
  • 18
0

Coding styles are bad habits. Difficult to get rid of. Best way of letting someone drop a bad habit? Let him see first-hand how ugly, disgusting or harmful it is.

Show them bad code, ask them what's bad about it. Let them think about it for a second, then give them an "Aaahaaa!" moment by showing them an edge case (Fencepost problem, perhaps?) or a case in which their bad design collapses everything else.

Your guys suffer from regular bad design problems, it seems. Show them one example of how a global function changed in an innocent way harms other functions depending on it, but not knowing it was changed. Show them a classic synchronization problem with the global variable.

Do it in a funny way to engage them, instead of boring them or making them take defensive positions (who is this guy to criticize us?); for example show them a function that does its job in two steps (1- enter wife's name)(2-store it in global)(3-enter husband's name and take wife's name from global to store in database)(4- laugh as bad synchronization results in men having 'new' wives), as a joke propose writing a divorce statistics function.

Believe can get butthurt about programming style, because we program what we think, and when programming design gets criticized some people take it as an insult to their way of thinking and hence their intelligence, so you must take a fun approach to it.

Take on of your bad functions, conceal it with some changes so as not to embarrass the code owner, and work & interact with the audience to improve it. Result: Your source code control system next morning will be so busy, so grab a coffee and smile at the change logs.

Orca
  • 101
  • 2