macOS Programming Style: lots of descriptive methods?

[GorillaPaws]

So I bought the video Clean Code by Dave Dribin which was from the MDN Conference 2010. Among many of the points he makes, one is using the strategy of breaking up your code into lots of descriptive convenience method calls, so it's self-documenting (almost like pseudocode). I've heard this approach advocated by Danny Greg on the Cocoa Fusion podcast as well.

They do make the caveat of being sensitive to performance concerns, and to make adjustments accordingly if there is an issue. I was wondering if this coding style had a name? If it's something you do with your code? If there are downsides other than the occasional performance issue, and having to jump around your code a bit more?

 

[Catfish_Man]

I would call this "self-documenting code"; it's a pretty basic assumption underlying any coding style I've ever heard of.

This is one reason C++ is nice, btw; The compiler's inliner can remove all that method call overhead. That said, if objc_msgSend is your bottleneck in an Objective-C app, it's generally easy enough to fix that one place.

 

[lee1210]

I certainly don't know a name for it, but I definitely use a lot of convenience methods day-to-day. Normally there will be one program unit that is somewhat sizable, where the real "flow" is so it's easy to follow what the general steps are in one place. Then I use a lot of small methods to do a lot of the work, especially for repeated tasks.

A real upside to this, in my experience, is that it's easy to write tests for these methods to ensure they work properly. The simpler the better for each. This doesn't trivialize putting it all together, but it's a lot easier when you have solid, known-good blocks as your foundation.

-Lee

 

[notjustjay]

I think a lot of it is common sense. It also depends on how easily your algorithm or process breaks down into discrete steps. A lot of the time your program is going to do this:

load data from saved file
get user input
process data
display processed data

At the top level, it might well make sense to break that down into methods like GetInputFileName(), LoadData(), etc. You certainly don't want to do too much in one great big long method. Sometimes things make logical breaks. A switch/case, for example, could call a different method for each case, otherwise your switch/case statement could end up being pages and pages long.

void ProcessMessage(int sourceID)
{
   switch (sourceID)
   {
      case FILE_SERVER_ID:
         processFileServerMessage();
         break;
      case DATABASE_ID:
         processDatabaseMessage();
         break;
      case ADMIN_PANEL_ID:
         processAdminMessage();
         break;
      // ... etc...
   }
}

I don't advocate ridiculous method names, like GetTheNameOfTheDataFileTheUserWantsToProcess(), but it should be reasonably intuitive.

 

[GorillaPaws]

One area that I would imagine would be helpful with this style is taking advantage of #pragma mark. Do you simply cluster all of your convenience methods in one place? or do you like to keep them close to where they're used (sort of like defining a local variable right before it's used as opposed to all at the top of the method)?

What are some organization strategies within your class when you have a lot of smaller methods?

 

[lloyddean]

For cross-platform code (where some compilers complain of unfamiliar pragma's) instead of '#pragma mark' I'd recommend using one of:

// MARK: -
// MARK: SUBROUTINES

or

/*
* MARK: -
* MARK: SUBROUTINES
*/

Both provide the same functionality within Xcode but the comment 'MARK:' method passes thru all compilers without complaint.

 

[gnasher729]

For cross-platform code (where some compilers complain of unfamiliar pragma's) instead of '#pragma mark' I'd recommend using one of:

// MARK: -
// MARK: SUBROUTINES

or

/*
* MARK: -
* MARK: SUBROUTINES
*/

Both provide the same functionality within Xcode but the comment 'MARK:' method passes thru all compilers without complaint.

One million thanks for that info.

 

[Cromulent]

For cross-platform code (where some compilers complain of unfamiliar pragma's) instead of '#pragma mark' I'd recommend using one of:

// MARK: -
// MARK: SUBROUTINES

or

/*
* MARK: -
* MARK: SUBROUTINES
*/

Both provide the same functionality within Xcode but the comment 'MARK:' method passes thru all compilers without complaint.

That's a top tip. Cheers.

 

[lloyddean]

Some other useful comments that place marker in the function menu include:


/*
* FIXME: See bug report <URL/BUG143>
* TODO: We may want to add feature <URL/TODO182>
* !!!: Warning beware the following consequences!
* ???: WTH Is this supposed to do?
*/

 

[crackpip]

Some other useful comments that place marker in the function menu include:


/*
* FIXME: See bug report <URL/BUG143>
* TODO: We may want to add feature <URL/TODO182>
* !!!: Warning beware the following consequences!
* ???: WTH Is this supposed to do?
*/

Damn, it pays to read through documentation. This works in Fortran, too.

Thanks for the tip, lloyddean.

crackpip

 

[lloyddean]

And then Control-2 will select the function menu from within Xcode. It make for easy navigation without moving the hands from the keyboard!

 

[Sydde]

I have one horrendously complicated Cocoa class that has several dozen methods. Sorting these into functional Category files (with descriptive names) makes the class much easier to navigate. It is probably not the best programming style, but it seems to work pretty well. I am sure any other programmer trying understand the class would have nightmares for weeks after, but it is solely my project.