Software Engineer Lessons Learned

Some unsorted things I've learned as a software engineer:

Tickets

1. Writing a ticket is like throwing an idea at the wall.  It may stick, it may bounce, it may kick the hornet's nest when a serious issue is raised.
2. If you have a task, a requirement, a feature idea, or have found a bug, write a ticket for it.  Tickets are cheap.
3. Yes, you will need to weed out stale tickets, already-fixed tickets, duplicates, and invalid tickets.  It's just part of the job.
4. It's better to record a bug in a ticket and forget about the ticket, than it is to have a coworker or a customer find a bug you forgot about and didn't ticket.
5. Good tickets describe the problem/task/issue and an acceptance criteria.
1. Bug tickets should describe the circumstances of the issue, or how to reproduce it.
2. Tickets without an acceptance criteria but with a problem or task may implicitly be accepted when the problem or task is solved.
3. Tickets without a clear task but with an acceptance criteria may result in an accepted ticket with an inadequate solution ... which is the ticket-writers problem.
6. One idea per ticket.  Tickets described with an "and" frequently should be split into two tickets. 
7. Tickets are not for documentation, but feature and requirements documentation may stem from tickets.

Version Control

1. Put everything you work on into a version control system.  Text, images, source code, documentation, meeting notes.  It's worth it for change tracking, easy backup, and collaboration.
2. Describe your commits.  "Fixed stuff" with twenty changed files means that I need to flip through twenty files to see that a copy-pasted typo was fixed.
3. Commits are cheap lightweight.  Make them small and frequent.
4. Repositories are expensive.  Each one has a wiki, an issue tracker, and its own commit ID set.  Add directories to an existing repository instead of creating a new repository, if able.
5. Commit descriptions are not the place for tickets, todo's, or documentation.  Put those in the ticket system or the wiki, respectively.
6. Commits should refer to a ticket, if able.  If it makes sense, create a ticket to go with the commit.
7. Branches are cheap, until you need to resolve merge conflicts.

Testing

1. If it isn't tested, you can't prove that it works.
1. If a complex system isn't working AND your code isn't tested, you can't prove that your code is blame-free.
2. If you can't test the parts, you can't prove the whole.
3. Testing for failure is sometimes as important as testing for success.
4. Tests are demonstrative.  Time spent writing good tests can double as time spent on documentation, as you wind up with working sample code.
5. If the tests are good and pass, but the product does not meet requirements, the tests are inadequate.  The problem is with the tests AND the product.
6. If the product meets requirements but does not satisfy the customer, the requirements were inadequate.  The problem is between the customer and the requirements gatherer.

Documentation

1. Good documentation is a rarity that must be structured in to a project, generally with technical writers.
2. Good tests can be turned into good documentation.
3. Documentation generators (JavaDoc, etc) are good ideas that are rarely followed.
1. These are best if they are required by policy or convention, rather than being left as a "good idea".
4. Documentation and project funding are directly proportional.