Today, I’m going to talk about the way my attitude towards using namespaces has pretty much done a complete reversal over the last couple of years.  I started off thinking that they looked great, progressed to mild concern that they seemed to be causing unexpected difficulties, and eventually realized that they can become unmanageable if allowed to grow out of control.  Just like a bunch of tribbles. (Yes, the title is a Star Trek reference :).

  To jump to the punch-line, I’ve come to the conclusion that highly fragmented hierarchies of namespaces (such as are found in .Net and encouraged by the Visual Studio C# IDE) make life harder rather than easier.  Instead, I would recommend either name mangling strategies (incorporating an identifying string in the object name) or always using fully qualified names in your code (instead of “using” statements).

Phase I: Infatuation

  When namespaces were first introduced into C++, I thought they looked like a great idea.  It seemed wonderful to not have to worry about managing name collisions.  Unfortunately, for over a decade I didn’t have an opportunity to use them; my Physics codes were standalone executables (and so name conflicts weren’t an issue), and ACIS was written before they were portable to all compilers.  Actually, ACIS was written before they were introduced into C++.  In the tribble analogy, everyone else got to play with these cool critters but I didn’t have one.

Phase II: Nagging Doubts

This changed when I started working with C#, especially in my personal projects at home.  The .Net library makes extensive use of namespaces to indicate areas of functionality, plus the Visual Studio IDE assumes you want this sort of hierarchy in your code.  If you create a folder within your solution to manage an area of functionality, for example a Market component in an economics simulator with root namespace Econ, then the Visual Studio class wizard “helpfully” puts any classes you add to that folder into the “Econ.Market” (sub-)namespace.  And that is where the trouble started.  (If anyone knows how to turn this behavior off, please post a reply – I’ve been unable to find a way to do it.)

I quickly found myself getting frustrated by not having the correct set of “using” statements in my code, and having difficulty figuring out which “using” statements I needed to include.  For example, if I had a Trader class in a Actors folder (and corresponding namespace) and a Pit class in the Market folder, then I would regularly get compile errors when I tried to use the Trader class without “using” statement for the Econ.Actor namespace.  And the really frustrating part was that it wasn’t immediately obvious which namespace was missing – I would have to find the class then look to see which namespace it was in.  I now realize that the problem that I was running into is that namespaces (or more precisely “using” statements) lead you to write non-self-documenting code.  In other words, if I write the code

Market market = new Market(); 
GoodsType goodsType = new GoodsType(); 
Pit pit = market.GetPit(goodsType);

I don’t have any visual indication in that region of code as to which namespace Pit, Market, or GoodsType live in.  And if they come from several namespaces, I don’t know which “using” statement corresponds to which class.

This is very similar to the C++ “which header file declares this class” problem, for which a really good solution is to simply make the header name identical to the class name.  CGM uses this naming convention and I highly recommend it – you don’t have to think when writing your include statements.

Phase III: Regret

The final driver on my voyage of discovery was C3D development (in C++).  When we first started writing strong commands, I had the bright idea to use a namespace hierarchy to put a structure on the vast sea of commands we would be writing.  Unfortunately, it didn’t work out as planned.  Even though we only introduced a few namespaces, they still made life much more difficult than a simple name mangling scheme would have.  Part of the problem is that the compiler errors when you get the namespace wrong are not helpful:  we had to train ourselves to ask “did we get the namespace right” when we see an “undefined symbol” error for a class that we’re sure has the header included.  An especially nasty error occurs when you try to include a header file inside a namespace block (this typically happens if you’re using templates and so want to do another round of includes for the method definitions).  If I had it to do over again, I’d settle for a simple “_SPA” or “_CGM” at the end of each class name, e.g. Property_SPA rather than Spatial::Commands::Property.  In tribble language, I feel like Kirk standing awash in a sea of tribbles.

Phase IV:  Lessons Learned

The first thing to make clear is that I am NOT saying that namespaces are bad.  The fundamental problem that namespaces solve is the ability for application writers to manage naming clashes between libraries from different vendors.  I think it’s a great idea for every company selling component software to put everything into a single company namespace.

The problems I see come from trying to group classes into complex hierarchies, especially if you then use “using” statements to erase knowledge of the hierarchies.  I’ve come to the conclusion that any such grouping should be as simple as possible, and that the primary goal of the grouping should be avoiding name clashes rather than imposing a component structure on the classes.  The reason for this is that classes move between components fairly easily, especially if the component structure is very fine-grain.  If every time a class moves you have to do a major renaming effort (either to fix using statements or to rename the class) then you’ll generate a lot of worthless work for yourself.

With this in mind, I currently think a name mangling scheme, with the disambiguating string at the end is best, i.e. something like ClassName_NS.  The reason for putting it at the end rather than at the beginning is to help search – if you’re looking for class “Beagle” but are not sure which namespace you’re in, then you just need to look for “Bea*” in a list of all class names.

All of the above being said, I shudder to think about trying to solve this problem in a huge organization.  Would .Net really be easier to use if they had used the above naming scheme rather than relying on namespaces?

This blog post describes some ideas I have about writing better code.  When one says “optimize” the first question I have is: what is the goal?  What are we optimizing for?  I think optimizing means maximizing the economic value of the software you are working on.  There is a subjective component to value that a developer has no control over.  However, there are a lot of things that influence value that are directly controlled by developers. 

With that, I will enumerate some key areas asking questions for each.  Remember that programming is hard, and there is no panacea that works for everything.  But these are some questions which help me think about what is working and what is not.

1. Use a specification/contract 

• Can developer reading only the signatures and inline comments figure out how to use the functionality?
• Is expert knowledge of the implementation required to understand what the functionality is going to do?
• When a bug occurs, how difficult is it to find the part(s) of the code that are responsible?
• Are contracts recorded in comments? Enforced as runtime checks? Enforced as compile time checks?

2. Handle errors consistently

• Do you use return codes?
• Do you use exceptions?
• Is it possible to debug failures easily (e.g., set one breakpoint for unexpected events)?
• In the event of an error, does the program silently produce unexpected results?
• In the event of an error, does the program offer an informative error message and avoid damaging the program state?
• Can the program recover from some failures to still produce a meaningful result?  (Please note: recovering from an error is completely different from ignoring it…)

3. Use interfaces

• To add a new functionality X, how much code needs to change?
• Do the function/method signatures make sense without reading the implementation code?
• Are there any functions/methods with more than six arguments?

4. Multithreading Friendliness

• How much static and global data is present?
• How monolithic are the algorithms?
• Can the big/time consuming parts of the algorithm be broken into non interacting pieces?

5. Know your programming tools

• Are you familiar with what STL can do, and how quickly? i. E.g., what does std::equal_range do?
• Are you familiar with Boost and other available utilities?
• Are you aware of domain specific libraries to help with what you are doing?
• Does your programming environment offer things like auto completion, cross referencing in the code, etc.? 
• How much do you need text find to navigate in your code?

6. Know your source control, build, and testing systems

• How long does it take a new employee to check out and build a copy of the product?
• Are automatic tests run regularly on the code?
• How long does a build take?
• If someone makes grossly incorrect changes to the code, how long does it take to recover from that?
• Are changes associated with stories/bug fixes?
• Can you obtain source for each version of your released product easily?
• Are dependencies noted between changes? i. e.g., if someone wanted a version of your product from 10 years ago, except with bug fixes x,y, and z applied, how long would it take to comply with that request?)

7. Performance

• How do you measure size/complexity of inputs?
• How does compute time scale with size of inputs?
• How does memory consumption scale with size of inputs?
• For a given hardware configuration, how large a problem can you handle without running into memory problems?

Do you, dear reader, have any questions or schema for accessing software and development quality that you would like to share?

Did anyone else notice in Prometheus (recent movie), that when they landed on the planet of the crazy space men, the ship's captain used something suspiciously like a laser scanner to get a 3D point cloud which mapped the tunnels in the alien city?

I thought that was really cool. Scanners like that actually exist today. (They are not the size of a golf ball, like the scanner in the movie was, but the principal is the same.)

Have you noticed anything like this lately where 3D modeling is shown prominently (or subtly) in movies or TV? Good perception is worthwhile because it might help get youngsters excited about math and science.

In my previous post, Creating a Better Documentation Experience, I covered highlights of our online documentation. This time we will dive into search methods, categories and navigation.

Using the Search Engine
The first, most obvious manner in finding what you need is to use the site Search. On the left side of your screen, the Navigation Side Bar contains a Search box with two buttons under it labeled Go and Search.

If you know the title of the article, the Search autocompletes your entry with one or more page titles (case-sensitive). You can then press the Go button and the Search takes you directly to that article.

Else, press Search if you simply want to search the text of all articles (this option is case-insensitive). You will be presented with a listing of Search results, or a message indicating that no matches were found.

For more tips on using the site Search, visit the Help on Searching page, which can be accessed by clicking Help on the Main Page (to the right of the Search box) or entering keywords such as help on searching in the Search.

Browsing by Category

Another method to locating what you need is browsing by Category. Spatial develops its product documentation on a MediaWiki platform. Therefore, each page is categorized so that you may find it by browsing the Category pages. You may choose to browse the complete list of categories, or you may choose to browse those specific to a product, such as ACIS, InterOp, or RADF.

Simply entering Category:ACIS Docs in the Search box will take you directly to that category and you will see that it has several subcategories, such as Advanced Blending, Components, and Local Operations.

Likewise, at the bottom of every technical article, notice that one or more categories are listed. This guides you to other similarly categorized pages and other related categories.

More Navigation Tips

And finally, as you browse through the articles, notice that many of them have breadcrumb navigation near the top of the page, or a See Also section near the end of the page. Following the breadcrumb trail takes you to a “parent” level page (usually a Portal page), while the links in the See Also section take you to related/recommended pages.

I hope this post helps you discover some key areas of our online product documentation, and helps you find what you need quickly. If you have any specific requests for future blog posts about our documentation, please leave a comment for us below.
 

The Spatial Product Documentation at doc.spatial.com is quite extensive...ok, let's just say it..."HUGE".

We get that. However, your experience with our product documentation can still be a really good one. And even though our online documentation consists of over 8,000 documents, you'll be pleased to see that the content is well-organized, searchable, and most importantly, helpful.

Hi. My name is Amalia Hurtado and I intend to help you improve your experience with Spatial's product documentation. With a series of blog posts, I plan to shed some light on the best features of our online documentation and help you locate what you need quickly.

Online Product Documentation Highlights
Did you know that Spatial’s online product documentation features . . . 

• An ACIS Getting Started Guide
• Multiple tutorials for step-by-step instructions on using ACIS
• Hundreds of ACIS FAQs and InterOp FAQs that describe how to perform typical functions. Many of these articles provide a C++ code sample, their signature, source files, and any applicable Scheme extensions.
• A comprehensive listing of ACIS error codes, their descriptions and complexities, while many provide a workaround for the issue
• Over 1,800 Scheme extensions with examples and images to assist your development efforts, and to troubleshoot issues with Support Services
• A mapping of Scheme extensions to their corresponding APIs
• A comprehensive listing of Scheme data types, ACIS options, and Law symbols
• Archived release notes so that you can easily determine what was developed and changed in previous releases of ACIS, InterOp, and RADF
• A listing of technical articles that were either new or improved, and articles that describe new product functionality for each release
• A glossary of key terms used throughout the product documentation
• And most recently, localized versions of the ACIS R23 Release Notes in Chinese, Japanese, and Korean, and of the InterOp R23 Release Notes in Chinese, Japanese, and Korean
   

In my next post I will outline how to best navigate our product documentation through the search engine, with categories, and I'll share some tips and tricks.