Archives

Cambridge Lean Coffee (Hiccupps)

On September 30, 2015, in Syndicated, by Association for Software Testing
0

Yesterday’s Cambridge Lean Coffee was hosted by Chris George at Cambridge Consultants. Here’s a brief note on the topics that made it to discussion in the group I was in.Can you quantify usability? Do you try?different for specialist, small-s…

My thoughts on documenting your code (The Continuous Improver)

On September 30, 2015, in Syndicated, by Association for Software Testing
0

A recurring topic in every project I’ve been involved with is when and where you should use XML comments and/or annotate classes and members with proper documentation. I’ve always been very specific about this, but in real live I meet a lot of developers who don’t seem to care about this, or worse, they reject the entire concept. Some of these people claim that the only real documentation is the code itself. And although I fully agree that a well-factored and properly named class is a crucial element in achieving a maintainable code base, proper documentation is just as important.




In my opinion, these three kinds of documentation are required for every professional code base.
  • Class-level and member-level documentation helps you understand what behavior to expect without having to jump into the actual implementation details. It should also explain the responsibilities and the roles the class plays in the overall design, or the member within the class. This kind of documentation is not a replacement for proper naming. Both are crucial, and one should reinforce the other. So always document the expected behavior of all your public and protected members. But, don’t add documentation that repeats the name of the member. I’d rather have no documentation at all than that kind of useless crap.
     
  • Inline comments, which you should use scarcely, are there to help you understand the thought process the original developer went through, to point you in the right direction, or to emphasize a particular non-trivial design decision. I use the word scarcely purposely, because in most cases, refactoring the code can help you avoid the need to have in-line comments. For instance, wrapping a complex expression in a method which name explains the goal of the algorithm can already make your code a lot easier to understand. Robert C. Martin’s book Clean Code contains numerous of these refactorings.
     
  • Commit comments should not only explain the nature of the change, but more importantly, why a particular change was needed in the first place. When a lot of people are involved, it becomes pretty important to be able to see why something that happened a long time ago happened. Yeah, an internal blog can help, but ultimately, it’s the source control history that will contain the really interesting changes. I’ve seen numerous occasions where I noticed some code that seem to be superfluous, but ended up being quite critical. The commit message for that change helped me understand why. Unfortunately I’ve also seen less helpful commit messages requiring me to figure out the reason the hard way.

So what do you think? Do you properly document your code? Does code documentation help you use an API? Or do you still jump into its implementation details? Let me know by participating in the Disqussions below. Oh and follow me at @ddoomen to get regular updates on my everlasting quest for better solutions.

My thoughts on documenting your code (The Continuous Improver)

On September 30, 2015, in Syndicated, by Association for Software Testing
0

A recurring topic in every project I’ve been involved with is when and where you should use XML comments and/or annotate classes and members with proper documentation. I’ve always been very specific about this, but in real live I meet a lot of developers who don’t seem to care about this, or worse, they reject the entire concept. Some of these people claim that the only real documentation is the code itself. And although I fully agree that a well-factored and properly named class is a crucial element in achieving a maintainable code base, proper documentation is just as important.




In my opinion, these three kinds of documentation are required for every professional code base.
  • Class-level and member-level documentation helps you understand what behavior to expect without having to jump into the actual implementation details. It should also explain the responsibilities and the roles the class plays in the overall design, or the member within the class. This kind of documentation is not a replacement for proper naming. Both are crucial, and one should reinforce the other. So always document the expected behavior of all your public and protected members. But, don’t add documentation that repeats the name of the member. I’d rather have no documentation at all than that kind of useless crap.
     
  • Inline comments, which you should use scarcely, are there to help you understand the thought process the original developer went through, to point you in the right direction, or to emphasize a particular non-trivial design decision. I use the word scarcely purposely, because in most cases, refactoring the code can help you avoid the need to have in-line comments. For instance, wrapping a complex expression in a method which name explains the goal of the algorithm can already make your code a lot easier to understand. Robert C. Martin’s book Clean Code contains numerous of these refactorings.
     
  • Commit comments should not only explain the nature of the change, but more importantly, why a particular change was needed in the first place. When a lot of people are involved, it becomes pretty important to be able to see why something that happened a long time ago happened. Yeah, an internal blog can help, but ultimately, it’s the source control history that will contain the really interesting changes. I’ve seen numerous occasions where I noticed some code that seem to be superfluous, but ended up being quite critical. The commit message for that change helped me understand why. Unfortunately I’ve also seen less helpful commit messages requiring me to figure out the reason the hard way.

So what do you think? Do you properly document your code? Does code documentation help you use an API? Or do you still jump into its implementation details? Let me know by participating in the Disqussions below. Oh and follow me at @ddoomen to get regular updates on my everlasting quest for better solutions.

Catching up on a few Conferences (Chris Kenst's Blog)

On September 30, 2015, in Syndicated, by Association for Software Testing
0

One of the great things about modern testing conferences is most either live stream or record their conference talks so the information can be disseminated to a wider audience. While you don’t get the interaction and conferring that an in-person …

What He Sed (Hiccupps)

On September 29, 2015, in Syndicated, by Association for Software Testing
0

I recently came into possession of an ancient O’Reilly book on the utilities sed and awk, tools that I use occasionally at work but have really only scratched the surface of. There’s a passage right at the start that chimed with me, and here it is as a…

BBST Foundations Week 3 In Review (Assert.This)

On September 28, 2015, in Syndicated, by Association for Software Testing
0

This is part 3 of my experience through the 4 week BBST Foundations Course. * Week 1 In Review * Week 2 In Review The Last Week Before the Exam This week was different from the previous two weeks. The exam study forum was open and possible test questions were listed, so you can work … [Read more…]

Writing Conference Proposals (The Pain and Gain of Edward Bear)

On September 27, 2015, in Syndicated, by Association for Software Testing
0

I have had some success with speaking at conferences (Nordic Testing Days 2013, Copenhagen Context 2014, TestBash NY 2015). That being said, I’m in no way on the plus side when you deduct the rejected proposals from the accepted ones (and then there are those I was on the brink of submitting but never did). […]

Wrong usage of metrics could be devastating (zagorski software tester)

On September 26, 2015, in Syndicated, by Association for Software Testing
0

credit: www.canddi.comTL;DRIn this blog post I will compare wrong usage of metric in economy and software testing.Croatian economy is on the wrong path. One of the main reasons is very low level of economy reforms. We are still in chains of econom…

Problem Solving Leadership: An Experience (The Pain and Gain of Edward Bear)

On September 23, 2015, in Syndicated, by Association for Software Testing
0

I’m back from the sunny Albuquerque, New Mexico having spent more than a week with some bright minds to figure out this problem solving business. For me, problems started even before PSL as Lufthansa canceled their flights. James reminded me this could all be Jerry’s doing… Considering it now after PSL I would not be […]

BBST Foundations Week 2 In Review (Assert.This)

On September 21, 2015, in Syndicated, by Association for Software Testing
0

So here we are at the end of week 2, halfway through BBST Foundations Course. Feel free to read my week 1 report if you want to see how I got here. I’m still here glad I signed up, but its been a bumpy week… Oracle Heuristics, and a Computer Science Primer We mainly focused … [Read more…]

Page 1 of 41234

Looking for something?

Use the form below to search the site:


Still not finding what you're looking for? Drop a comment on a post or contact us so we can take care of it!