Muokkaa otsikon tekstimuotoa napsauttamalla

Muokkaa jsennyksen tekstimuotoa napsauttamallaToinen jsennystasoKolmas jsennystasoNeljs jsennystasoViides jsennystasoKuudes jsennystasoSeitsems jsennystasoKahdeksas jsennystasoYhdekss jsennystaso

/

Dutch Perl Workshop 2016

Documenting Code
Patterns and Anti-patterns
Sren Lund (slu)
slu@369.dk

Content of This Talk

Introduction

About Me

DocumentationWhat Documentation Do We Need?

Comments in CodeComment Patterns

Comment Anti-Patterns

Inspiration Strikes

During a code review I saw a comment

The comment tried to document the code, which was not easy to understand

I suggested refactoring the code, thus eliminating the need of the comment.

The developer agreed and did the refactoring

I got inspiration for this talk

Rewriting the Title of the Talk

First title was
Please don't comment your Perl code

I found it too negative, so I changed it to
Don't comment code, document it

Still starting of negative, so I came up with
Documenting Code, Patterns and Anti-patterns

I.e. writing (coding) is hard; and you need to constantly rewrite (refactor).

This Talk is for Developers

It's about documenting code

How to make it easier for the (next) developer

About Me

I'm a freelance consultantWeb Development, later years mainly Back-End

Build & Release Mgnt, Testing & CI, DevOps

Professional developer for more than 20 years

Programmed in Perl for almost as long

Generalist, work with everything from infrastructure to front-end-development

I enjoy writing (the right) documentation

Documentation

The Problem with Documentation

Documentation must be in sync with the code

It's extra work. Often missed/skipped.

Minimize the amount of documentation, will results in less workWrite code that is self-explanatory

We'll still need some documentation

Self-Explanatory Code

Meaningful naming is important

Short subs

Minimize block level

A module/sub should do only one thing

Don't be afraid of one-liner subs

Comments are rarely/never needed

Ensuring Self-Explanatory Code 1

Create Tests (which is a form of documentation)Unit Tests (prove)

Function/Integration Tests (JMeter, Postman, Selenium)

When you create tests, you mindset changes

You'll be using your own code

Remember to run test daily in CI (Jenkins)

Ensuring Self-Explanatory Code 2

Peer Review (Crucible, Gerrit, PRs)

Remember to review tests and documentation

An effective way to knowledge share (eliminating the need for documentation somewhat)

Project of the Month/SprintReview/clean-up/elimination of technical debt

Do the damn peer reviews!

software testing alone has limited effectiveness the average defect detection rate is only 25 percent for unit testing, 35 percent for function testing, and 45 percent for integration testing. In contrast, the average effectiveness of design and code inspections are 55 and 60 percentSteve McConnell, Code Complete

What Documentation Do We Need?

The README file

Placed in the top level directory of the code

This is what e.g. CPAN and GitHub wants

Content should includeShort description incl. copyright information

How to build/install

Links to issue tracker, wiki, etc.

The Issue Tracker

JIRA, Redmine, Bugzilla, Trac, GitHub...

Use it to document known bugs

describe wishes (coming features)

prioritize what to do next

Should support your development process

A Wiki

Confluence, Redmine, Trac, GitHub

Use it towrite Technical Notes

communicate ideas (drafts of e.g. APIs)

maintain a FAQ, knowledge base, etc.

write User Documentation (not always an option)

Specific Documents We Need

Architectural Notes (hows and whys)

Code Style Guidelines (maybe just point to http://perldoc.perl.org/perlstyle.html)

Server/Deployment diagram (simplified)

E/R Diagram (auto generated, SchemaSpy)

Should all be (available) in the Wiki

Note: Customer/Company might require you to write other documentation.

Comments in Code

Don't Comment Code

The proper use of comments is to compensate for our failure to express ourself in code. Robert C. Martin, Clean Code: A Handbook of Agile Software Craftmanship

You should fix the code by refactoring it, not by commenting it

But comments can be used for good

I.e. there are patterns and anti-patterns

Comment Patterns

File Header

Comments at the top of (each) source file

Can contain a short description and/or

include copyright information (which should be auto inserted)

The README file might suffice

Mainly useful for procedural scripts

Why-And

Used when you're adding Technical DebtThe code might not be self-explanatory

Document why you had to do it and how to eliminate itThe next developer wont think badly about you

Helpful Links

Use when implementing an algorithm or very specific requirement

Insert a link or reference

Example:

# Calculate PI using Bellard's formula
# See http://en.wikipedia.org/wiki/Bellard%27s_formula

Public APIs

Used when creating a (CPAN) module/script that's used by others

Use POD markup
(http://perldoc.perl.org/perlpod.html)

This is documentation, which needs to be in sync with the codeit's close to the code, thus a little easier to keep it in sync

Comment Anti-Patterns

Stating the Obvious

Example:

# initialize counter
$count = 0;

Problem: It's just noise

Solution: Just remove the comment

Refactoring in Comments

Example:

# n is number of files
my $n;

Problem: You spotted an issue, but didn't fix it

Refactor, example:

my $number_of_files;

Issue Tracking

Example:

# TODO: will crash if configuration file is empty

Called Source Code Task Tags (variants: FIXME and XXX)

Create corresponding issues in Issue Tracker

And perhaps convert to Why-And comment

Disabling Code

Example:

# say count = $count

Problem: it's old/unused code

remove it (if it's not needed anymore)

commit to a branch (it you might need it)and remove it from mainline

put it behind a feature/debug flag

The End

Write self-explanatory code with tests

Do formal peer reviews

Eliminate the comments

Maintain a minimal set of documentation

Any Questions?