Skip to main content

Home/ SoftwareEngineering/ Group items matching "macros" in title, tags, annotations or url

Group items matching
in title, tags, annotations or url

Sort By: Relevance | Date Filter: All | Bookmarks | Topics Simple Middle
kuni katsuya

Preemptive commit comments | Arialdo Martini - 0 views

arialdomartini.wordpress.com/...pre-emptive-commit-comments

BDD BehaviorDrivenDevelopment CommitComment BestPractices SoftwareEngineering

shared by kuni katsuya on 15 Mar 13 - No Cached
  • Tell me what the software does
    • kuni katsuya
      kuni katsuya on 15 Mar 13
       
      tell me how the software should *behave*, not how the behavior was *implemented* ie. describe the changes in this commit from the behavioral perspective rather than implementation details
  • What is the project behavior, in this snapshot?
  • What did the programmers, in order to produce this snapshot?
  • ...43 more annotations...
  • committing comments describing the
  • behavior of the software,
  • rather than the
  • implementation or a description of what we did
  • commits’ comments started to look like BDD’s methods name: a description of a behavior.
  • principles
  • Talk about the feature, not about yourself
  • Don’t refer to the past
  • I know it’s now
  • list of benefits
  • More focus while developing
  • Commit review is much easier
  • Less cognitive load
  • You learn commenting much more precisely
  • commit comment becomes a
  • declaration of intent
  • like a BDD method name
  • No more “Just a fix“, “Improvements” or “I made this, this, this and also this” comments.
    • kuni katsuya
      kuni katsuya on 15 Mar 13
       
      BDD/TDD or any methodology aside, these are the worst commit comments as they are as useless as empty commit comments
  • Each preemptive comment triggers a micro design session
  • A preemptive comment sets a micro goal
    • kuni katsuya
      kuni katsuya on 15 Mar 13
       
      which also aligns well with the 'micro goal' or incremental deliverables approaches of most agile methodologies 
  • helps to focus a goal to be reached
  • Without preemptive comments, I often went on coding, always asking myself: “Should I commit now? Have I reached a stable state which I could consider a good commit?“
  • define micro-goals through preemptive comments
  • macro-goal through the feature branch name
  • A preemptive comment creates a little timebox
    • kuni katsuya
      kuni katsuya on 15 Mar 13
       
      similar to the timeboxing strategy of a short sprints, for instance
  • Writing comments preemptively puts the agreement between the pair members to a test
    • kuni katsuya
      kuni katsuya on 15 Mar 13
       
      more relevant to methodologies using pair programming
  • commit history gains a very balanced granularity
  • feature branch becomes a collection of evolutionary commits each of which has usually a 1:1 binding with tests
  • very easy to find which commit introduced a bug, since each commit is related to a single new goal/feature
  • Preemptive commit comments
  • Rule #2: write what the software
  • I started taking a lot of care of the words I was using in comments, commits, test names and classes/variables/methods’ names
  • be supposed to do,
  • not what you did
  • should
  • Introducing BDD
  • began with the simple attempt to replace the world
  • “should“
  • “test”
  • with the world
  • Rule #1: write commit comments before coding
  • use the same criteria for my commits’ comments as well.
  • (not what you did)
1 - 2 of 2
Showing 20▼ items per page