The document discusses essential lessons learned from a decade of game development, emphasizing the importance of communication and collaboration among various team roles, similar to a baseball team. It critiques the common pitfalls of code commenting and documentation practices while advocating for self-documenting code and automating documentation through development tools. The author, Jimmy Sieben, shares insights on how to enhance teamwork, streamline development processes, and maintain effective communication for better software quality.

1. NO
PROGRAMMER
IS AN ISLAND
LESSONS ON WORKING WELL WITH OTHERS
FROM A DECADE OF GAME DEVELOPMENT
Jimmy Sieben
Lead Programmer, Gearbox Software
Twitter: @jimmys
jimmy.sieben@gearboxsoftware.com

2. “NO MAN IS AN
ISLAND”
“No man is an iland, intire of it selfe; every man is a peece of
the Continent, a part of the maine; if a clod bee washed away
by the Sea, Europe is the lesse, as well as if a Promontorie
were, as well as if a Mannor of thy friends or of thine owne
were; any mans death diminishes me, because I am involved
in Mankinde; And therefore never send to know for whom the
bell tolls; It tolls for thee....”
John Donne (1624)
Meditation 17
Devotions upon Emergent Occasions

3. A WORD ABOUT ME
I have been programming for 20+ years (15 professionally)
I am a game maker since 1995
I joined Gearbox in 2002
Network & Game Programming on multiple titles
• Halo: Combat Evolved (PC)
• Brothers in Arms: Road to Hill 30 (PC/Xbox)
• Brothers in Arms: Hell’s Highway (PC/PS3/Xbox 360)
• Borderlands 1 (PC/PS3/Xbox 360)
• Borderlands 2 (PC/PS3/Xbox 360)

4. HOW ARE CODERS LIKE
BASEBALL PLAYERS?
PROGRAMMERS: BASEBALL PLAYERS:

5. HOW ARE CODERS LIKE
BASEBALL PLAYERS?
PROGRAMMERS: BASEBALL PLAYERS:
Coding is (mostly) an individual
activity
Work (mostly) alone before
integrating
Success depends on careful
collaboration and communication
Hitting is (mostly) an individual
activity
Hit (mostly) alone before game
finishes
Winning depends on teammates
and manager working together
Like Baseball, Software Development is a Team Sport

6. WHO IS ON THE
TEAM?
Developers
• Programmers
• Artists
• Animators
• Game Designers
• Sound Designers
• UI Designers
Other Disciplines
• QA
• Managers / Producers
• Business / Marketing / Support
Success requires great communication

7. COMMUNICATING
WITH PROGRAMMERS
Email
IM / Text / Twitter
Documentation
Code!

8. COMMUNICATING IN
CODE
Comments are a tool provided by almost every language
Come in many forms
• Line comments
• Block comments
• Javadoc or Doxygen-style comments
I think you should use comments sparingly!

9. THE
PROBLEM
WITH
COMMENTS

10. THEY ARE OFTEN NOT
UPDATED!
This is actual code in a shipped title!
// do not initialize the
// sound system here
InitializeSound();
Remove the comment?
Change the code?

11. THEY OFTEN DON’T
TELL YOU ANYTHING!
// open the file
FILE* fp = fopen(“data.txt”, “r”);
Obvious to C programmers what this does
Why? What do we expect?

12. THEY OFTEN DON’T TELL
YOU WHAT YOU NEED!
/**
* Sets the name of the player
* @param Name New name of the player
*/
function SetName(string Name);
Restating method name and arguments provides no value.
Who depends on this method and data?
What happens if Name is null or blank? Is that an error?

13. WHAT CAN
WE DO
INSTEAD?
IF COMMENTS MAY BE OVERUSED…

14. SELF-DOCUMENTING
CODE
Write code using names that clearly map to the problem
Avoid variables like var, x, foo, thing, obj…
Method / function names describe how the state of the
program changes
Avoid complex conditional logic that is hard to parse
Reading the code should tell you what it does

15. Nested loops are notorious for bugs with transposed variable names. Avoiding ‘i’ and ‘j’
here helps to ensure the loop is written correctly.
GOOD VARIABLE NAMES

16. Method names describe clearly the intent, and the code reads naturally
METHOD NAMES ARE CLEAR

17. This is a good example of breaking up a complex conditional into simple statements.
This reads much like the design documentation.
AVOIDING COMPLEX CONDITIONALS

18. WHEN TO COMMENT?
Non-obvious implementation detail
Tricky math or logic
• Although this is often a cue to consider re-writing the code…
Attribution of another’s work
When you change external code
Important assumption or dependency
• Although those are often better expressed as asserts or
exceptions…

19. Here’s an example of something that may seem strange at first. These arrays are used
in other methods and avoiding memory allocation is a key goal of this class.
NON-OBVIOUS IMPLEMENTATION DETAIL

20. This demonstrates both some tricky math, and attributing someone else’s work.
TRICKY MATH AND ATTRIBUTION

21. This developer added code to a file managed by a third party. His comments help future
merges later on.
EXTERNAL CODE

22. This developer added a feature to code managed by a third party. This helps prevent a
future merge from accidentally removing this new feature.
EXTERNAL CODE

23. These comments document an important dependency that is difficult to encode in any
other way. Hopefully the next programmer to come along heeds this warning.
IMPORTANT DEPENDENCY

24. GOING
BEYOND
CODE

25. OTHER WAYS TO
COMMUNICATE
Not all team members will read the code
• Code base is too large for all programmers to see
• Not everyone is a programmer
• Not all programmers understand all languages
How else can we communicate?
• Email
• IM / Text / Twitter
• Documentation
• Code!

26. DOCUMENTATION:
THEORY
In theory, this is a great idea
Write up descriptions of systems and features
Keep it up to date as you make changes
Whenever you encounter a new system, read the docs

27. DOCUMENTATION:
PRACTICE
In practice, this almost never happens
Unfortunately there is very little time to write docs
There is even less time to update them!
If it is written, it’s almost never read
Programmers grow to not trust the docs
In a fast-paced world, everything gets out of date quickly

28. WHAT DOCS
SHOULD BE
WRITTEN?
NOT ALL DOCS ARE BAD…

29. WHAT TO BE SURE TO
DOCUMENT
User guides to on-board team members
Overall system architecture
Intended use cases, dos and don’ts
Anything you are going to give to an outsider
• Customer
• Contractor
• Partner

30. HOW I WRITE
DOCUMENTATION
Structure it like an outline
• Introduction
• Definitions
• Content
• Conclusion
Develop a style guide and stay consistent
Use lots of whitespace!
Use lots of bullet points and lists
Keep prose to a minimum
Good documentation should be scannable

31. Title, an introduction stating purpose, and steps to setup the tool are prominent.
DOCUMENTATION STRUCTURE

32. In this document, dense log text is clearly and cleanly separated from the annotation.
DOCUMENTATION STRUCTURE

33. This example shows usage of whitespace to make the commands scannable
DOCUMENTATION AND WHITESPACE

34. This example shows denser descriptions. Note the use of headings and tables to help
the reader organize and scan the document.
DOCUMENTATION AND DESCRIPTIONS

35. BEYOND
WRITTEN
DOCS?
IS THERE ANYTHING…

36. ANOTHER APPROACH
TO DOCUMENTATION
Written docs are rarely written or read
We need something that is written automatically
We need something that team members will refer to
It must be integrated into the development process
Development Tools are the Answer!
• Source Control
• Perforce, Subversion, Git
• Issue Tracker
• JIRA, Bugzilla, FogBugz, TestTrack Pro

37. SOURCE CONTROL
AND ISSUE TRACKERS
Important components of any professional software
development project
Tracks work items and changes over time
Describes what happened
• Checkin description
• Work progress comments, Resolution notes
• Metadata (open date, reopen count)
Linked to the code, consider it part of the software

38. ONE CHECKIN, ONE
CHANGE
Checkins should be atomic, describing a single logical
change and a single unit of work.
This helps to keep your work organized
• Regular progress in rhythm
• Never lose much work in case of catastrophe
• Avoid the “end of day” checkin anti-pattern
Facilitates merging and rollback
Signs your work may not be atomic
• Checkin Comment uses words like “and”, “also”
• Comment has a list of bullet points

39. HOW TO WRITE
CHECKIN COMMENTS
Don’t just describe what you did, diff tools tell you that
Go higher level and talk about intent
Describe why the change was made
Indicate what are the implications of the change
Who is affected by this change?
For optimizations, give the results you have measured!
Link back to Issue Tracker as appropriate
Write a short summary first, and give more details later

40. CHECKIN COMMENT
EXAMPLES
WILLOWTWO-63204. Moved the invocation of player event
RevivingPlayer to WillowPlayerController.Behavior_StartRevive()
from AWillowPlayerPawn::SetRevivePct(). The previous location
was being called from a Tick() function so there was sometimes a
delay before the event would occur. The new location also calls
ForcePostPlayerEvent() since the current implementation of
PostPlayerEvent() can result in the event being ignored if it occurs
within 3 seconds of a prior player event.
This comment does the following:
• Link to the Issue Tracker
• Describes why the bug occurs
• Notes a new side effect

41. CHECKIN COMMENT
EXAMPLES
bug http://jira/browse/WILLOWTWO-63097 - BA Rank is reset when players join a
splitscreen game on a second controller with an existing character previously assigned
to another controller and then reload the game from the title screen
- Reset the PS3 OnlineSubsystem's cached profile for controllers who are backing out
to the title screen. The next time that controller advances through the title screen, their
profile will be re-read and re-cached appropriately. This fixes a bug where a user could
sign in as a splitscreen player with the same profile as the host (which would set their
profile to defaults since a slave to the host can't write their own profile settings) and
never have their profile re-read when they sign back in as a full-fledged user (because
the cached profile still existed and they never selected a new user account).
This comment also refers to a bug. It does the following well:
• Links to the Issue Tracker
• Describes Why the bug occurs
• Identifies how the bug is mitigated
• Summarizes first, gives details later

42. CHECKIN COMMENT
EXAMPLES
Added the option
bUseOneAsBaseValueForPresentationIfContextFailsToResolve to
AttributePresentationDefinition. This allows presentations for attributes that
don't exist on the item to still have a presentation on the item card.
The immediate use case for this is getting the critical hit bonus on guns like
Moxxi's Bad Touch and The Hawk Eye Seraph gun in Sage. The critical hit
bonus is a player attribute so guns that don't have a reference back to the
player when these stats are generated wouldn't consistently show this stat.
Included in this changelist is the hardocoded micropatch which enables this
option on the critical hit bonus attribute presentation.
SAGE-1886
This one describes a use case for a new feature, and it was
implemented as part of a larger series of changes.

43. CHECKIN COMMENT
EXAMPLES
(WILLOWTWO-63057) - Adding extended license info.
DownloadablePackageDefinitions can now opt in for 'extended licensing',
which means they are allowed to license individual items out of the
package. During DLC installation, the set of all DLC licensed content is
sorted such that all extended license items are at the front of the list, and
in an order determined by their package id, license mask, and content id;
both client and server will have the same ordering.
The ordering primarily determines which bit in the
DlcCompatibilityDataEx struct represents a
DownloadableContentDefinition. This new 128 bit struct is transmitted to
the server on login, and again whenever the client's license information
changes. The struct can be extended later if we need more room.
This comment gives an explanation for a feature as well as a
hint for how it can be used in the future. This explains intent.

44. WHY DOCUMENTATION
VIA TOOLS WORKS
There is a broad audience
• Programmers
• Content Team
• Managers
• QA
• The Future You!
It’s already part of your workflow
• Research, Develop, Test, Checkin, Resolve
Improves the quality of the software

45. SOFTWARE QUALITY
IMPROVEMENTS
Facilitates communication
• Teammates can find the hidden connections
• Scheduling is easier when information is available
Research the history to answer questions
• Who wrote this? Why? In what context?
• How has this changed over time?
Helps you write better code!

46. GOOD CHECKIN
PRACTICES == BETTER
CODE
Start by diffing all the changes
Describe why your change works, pitfalls, etc
Sometimes you find a bug when you think it through like this!
Sometimes you think of a new optimization!
Sometimes you find a typo or temporary debug code you
don’t want to checkin!

47. FROM CHECKIN TO
ISSUE TRACKER
Now that your change is checked in, resolve the issue and
write a good comment
Signals to team work is complete
• QA can test
• Producer can unblock dependencies
• Colleagues can review work and learn about what you did

48. WRITING GOOD ISSUE
TRACKER COMMENTS
Similar rules to checkin comments
• In fact, some developers just copy/paste
• I like to consider them as different audiences
Link to the checkin: changelist #, commit hash
Summarize work done, identify future work
Indicate how to test the change
Explain impact to your colleagues

49. GOING
WIDE
SHOW OFF!

50. SHOWING OFF YOUR
WORK
You just implemented a great new feature!
Designers are going to love it!
But, how do you let them know about it?
• Schedule a Demonstration Meeting?
• Write an Email with Instructions?
• Point them at Documentation you wrote?

51. DOCUMENTING A
FEATURE: BLOGS & WIKI
Don’t leave the details in an email
Write a blog post or an entry in Wiki instead!
Use email to point others at the docs
• TL;DR: Provide a summary to help others prioritize
• Invite and promote the use of docs for others
• Always use a good Subject line. This is valuable real estate!
Gives a context for questions and feedback
Persistent history of the feature

52. FEATURE
ANNOUNCEMENT
EXAMPLE
Subject: Enemies Can Now Fly!
TL;DR: Now you can make your enemies fly!
I added a cool new feature today that has been talked about for a few
days. You can make your enemies fly with just a few updates to the
content. I wrote the instructions on the wiki here:
http://wiki/WILLOWTWO/Enemies+Fly.html
Check it out and let me know if there is anything wrong!
This helps team members understand if the feature
announcement is relevant, and keeps the doc somewhere it
is accessible in the future.

53. FINAL THOUGHTS
Communication is key to making software
Remember you have a broad audience
Build discipline, work within team and tools
Challenge each other to improve each day
• A few “good apples” can inspire others
• Be the good example, don’t wallow in the mud
• Anyone on the team can be a leader in this area
Jimmy Sieben
Lead Programmer, Gearbox Software
Twitter: @jimmys
jimmy.sieben@gearboxsoftware.com