Is the difficulty of debugging complex games non-linear?

[sebbbi]

I try to explain why game developers and many other agile developers dislike huge design documents in general...

The most important thing is: Documentation and comments always end up being lies eventually. Modern coding standards should always prefer readable code over comments and/or low level documentation. If you choose good names for classes/structures, functions, data members and variables AND split the code to small enough (well named) functions/classes, you don't need many comments. The code is human readable and the names chosen describe the code clearly.

Comments do not maintain themselves, and there are no unit tests to prove that comments stay correct. Less comments = less lies.

The same is true for documentation. Low level documentation duplicating the information found in the code provides no extra information and is a pain to maintain. It adds inertia to code modification (and that leads to harder maintenance = less maintenance = code rot = decreased productivity = more bugs). High level documentation is important because that helps programmers to understand the architecture at a broader scale and the documentation helps programmers to find what they need (instead of creating their own code for already existing functionality). High level documentation is much easier to maintain, so it doesn't add much inertia.

Unit tests itself provide the programmers good low level documentation. Unit tests should be well named and should cover all the library use cases. Unit tests get compiled for every build, ensuring that the code works the way intended. Unit tests never become lies.

Sometimes of course you need additional documentation. For example you need a best practices guide for your vector math library. A good way to maintain documentation for an API like this is to tie the documentation and the unit tests together. In the document, you refer to the unit tests (all code examples in the documentation MUST have unit test cases to prove that the examples are correct) and in the unit test C++ files you have a link to the document (we use a wiki-style online documentation that every programmer can edit). This ensures that whenever the API functionality is changed in a way that requires a documentation change, an unit test will fail, and the programmer must fix the unit test first and then update the online documentation accordingly.

 

[function]

Do use anything like Hungarian Notation to aid code readability?

 

[BRiT]

Do use anything like Hungarian Notation to aid code readability?

That's diametric opposite to code readability and abstraction. From my experience things like Hungarian notation and forced suffix/prefix is pure evil. It doesnt get updated with changes and hence is very prone to become lies.

However I'm interested in sebbis experience with that.

 

[Davros]

That's diametric opposite to code readability and abstraction. From my experience things like Hungarian notation and forced suffix/prefix is pure evil. It doesnt get updated with changes and hence is very prone to become lies.

Then your problem is that your programmers cant follow guidelines, not the notation

I remember the guy next to me in college had a very strange bug, his program would occasionally start playing the birdy song, turns out I replaced one of his turbo pascal units with a slightly modifed one

 

[BRiT]

Then your problem is that your programmers cant follow guidelines, not the notation

No. My problem is with the notation. I have fundamental issues with the notation. It is pure evil; Hungarian notation is diametric opposite to data abstraction and encapsulation.

 

[Davros]

from wiki
"Hungarian notation is an identifier naming convention in computer programming, in which the name of a variable or function indicates its type or intended use."
dont see whats so evil about it and i dont see why you cant encapsulate data because youve followed a naming convention with the variable name used to hold that data

 

[Ethatron]

Well, if you want to abstract type (hide it, disconnect from it, make it variable, ...) and then note it in the name, it's diametral, isn't it?

 

[BRiT]

vUsing adjHungarian nnotation vmakes nreading ncode adjdifficult.

Hungarian Notation is an archaic notion from the days when your development environment and tools were practically worthless. From when you used simply text editors that could provide no insights into your code base. With modern day tools Hungarian Notation is entirely worthless at best and t worst it actually hinders the readability of the code.

Simple scenario that maybe you can understand.
You have a collection of items. Hungarian Notation would possibly want you to name this: collectionItems [colItems]
You don't care how that collection is implemented. That's the beauty of data abstraction.
Using your lovely Hungarian notation, that collection would be the following: listItems [lItems or lstItems].
Now someone does basic profiling and determines it's more effective to do storage and retrieval from an array backing store. Hungarian Notation dictates that should now be called: arrayItems [aItems or arrItems].

What if the backing store is via a HashTable, does your collection variable now need to be renamed to hashTableItems [htItems]?

Now if you're storing strings do you name it: htItemsStrings or htItemSt?

Better yet, use generics with the item type being stored in your list. So instead of 'items<T>' you now have your backing store called: arrItemsObj or htItemsObj.



How do any of those variable names help one damn bit? They do not. They break the concept of data abstraction.

See, that right there is pointless. The information should be maintained in the runtime / compile-time type safety systems and not be forced upon the actual variable name.

 

[Davros]

How do any of those variable names help one damn bit?

htItemsStrings tells me its a hashtable containing strings, thats usefull calling it bob tells me nothing
when I see a variable I should be able to tell just from the name its function and its data type.

As for your other question it seems to be "if you decide to change the datatype a variable stores should you rename it" well yes every ide has a search and replace all function its a 10 second job.
I have a variable called ArrayItems it stores a hastable makes no sense and it just wrong

 

[BRiT]

htItemsStrings tells me its a hashtable containing strings, thats usefull calling it bob tells me nothing
when I see a variable I should be able to tell just from the name its function and its data type.

And that is diametric opposite to data abstraction. Perhaps you should wiki that too.

 

[HTupolev]

htItemsStrings tells me its a hashtable containing strings, thats usefull calling it bob tells me nothing
when I see a variable I should be able to tell just from the name its function and its data type.

Why do you need to get that from the name?

The whole point of a lot of modern IDE features is that you can smoothly decouple stuff. Why blend data type with the name if you can see the data type easily anyway?

As for your other question it seems to be "if you decide to change the datatype a variable stores should you rename it" well yes every ide has a search and replace all function its a 10 second job.

That's annoying, and not necessarily reliable in real-world development.

 

[Davros]

Why do you need to get that from the name?

where am i supposed to get it from the variable declaration ? what if I am dealing with dozens of variables am i going to remember what type each variable is

That's annoying, and not necessarily reliable in real-world development.

more annoying than for example a variable that suggests its an integer when it isnt ? you may know it no longer holds an int but is someone reading your code 10 years into the future ?
As for search and replace all ive never known it to be unreliable

 

[Shifty Geezer]

htItemsStrings tells me its a hashtable containing strings, thats usefull calling it bob tells me nothing

Adding somewhat needlessly to the discussion, you wouldn't call your thing 'bob' if that doesn't describe it in any way. If it's a hash table of place names, you'd call it placeNames (about the only convention I use is lower case first letter for variables/fields, upper case first letter for functions/methods/classes, caps for constants). To know how to access the content of placeNames correctly, you'd hover the mouse over it and a tooltip will tell you what class it is. And/or you type 'placeNames.' and get a list of things to do with placeNames. Very useful for a new language (user) as you don't need to know every method available. Type a thing, hit the dot, and get a list of stuff you can do with it. Scroll through the list and sometimes you see a method name that opens up an opportunity.

Readability of code can be very good these days, although one has to get one's head around the annoying double names being different things. eg. Unity example in C# "GameObject gameObject" is an object of type GameObject called gameObject. Example code and tutorials abound with this, with field names being named what they are, and making early days of use annoying as the only distinction when trying to read someone's writing about gameobjects is whether there's a capital or not. If the thing was instead called "GameObject shipObject" or rockObject or something more descriptive, not even needing the Object suffix, it'd be easier to follow.

So I agree with the others that typed variable names is now redundant and obfuscates code readability.

where am i supposed to get it from the variable declaration ? what if I am dealing with dozens of variables am i going to remember what type each variable is

If it's code your working on, yes. It's only an issue if you're going over older code or linking with some other code that's not fresh in your memory. But a code variable name will have clear connotations. eg. loopCount is an int. objPos is a Vector 2 or 3 of floats depending on 2D or 3D app. playerName is a string. If it's not intrinsically obvious from the variable's name what type it is and what role it plays, it's probably badly named.

 

[Davros]

If it's a hash table of place names, you'd call it placeNames

Id probably call it Hashtabl_Str_Placenames or similar
if it was a hastable of numbers instead called placeNumbers how am I to know if its an integer or a byte or a word or a single ect ?

 

[Shifty Geezer]

Id probably call it Hashtabl_Str_Placenames or similar
if it was a hastable of numbers instead called placeNumbers how am I to know if its an integer or a byte or a word or a single ect ?

The fact it's called placeNumbers tells you its a collection of some form, so not an int or byte. If one's not happy using the IDE to describe a field for you, one can always add a datatype prefix/suffix for clarity, but it's not necessary for every variable and it does inhibit reading of general code.

 

[HTupolev]

where am i supposed to get it from the variable declaration ? what if I am dealing with dozens of variables am i going to remember what type each variable is

Like people have mentioned: in a modern IDE, that information is usually easily accessible via mouseover or some such business.

more annoying than for example a variable that suggests its an integer when it isnt ? you may know it no longer holds an int but is someone reading your code 10 years into the future ?

Why are you assuming that an alternative naming method would put the type in the name?

The alternative that I'm mostly alluding to is to avoid putting things in the name that are coupled to other aspects of the variable.

As for search and replace all ive never known it to be unreliable

The function isn't. The people using it can be, though. If feasible, it's usually best to not have to go down a checklist when you change something in the first place.

 

[Ethatron]

@Davros
One of your assumptions is, that you want to know the type. Mostly that only serves geeky interest. Most of the time the exact type isn't relevant except for some hardcore lowlevel code; the API for a list or a vector might (and should for the set of intersection of functionality) be identical, so that you can change the type transparently. Not only do you not need to rename you variables (which could cause 40k source files being updated, and copy'n'replace search'n'replace will blow your codebase to oblivion, it's not that simple), you also don't need to change the function calls either. And that is only possible because you design the APIs keeping type-flexibility in mind. You can protoype faster, and you also have to remember less API.

And that's only the perspective for plain old C. If you program in C++ it clearly becomes an unsolvable task to stay true to a type in the name once inheritance and templates comes into play. What is an "item"? Is it a "general purpose item", or is it rather a "droppable item" or really maybe a "immaterial item"? Is it "sometimesAFloatAndSometimesAInt"? Is the correct type the interface-"item" or, maybe because you wrote a spezialization of the interface-"item", rather something else.

It's very prone to be a lie, and sometimes if you manage to make it no lie, it is likely meaningless.

Finding good names for variables is hard, and I guess the relative simplicity of spelling out the type, makes it feel less of a struggle, maybe.

edit: corrected a mental typo

 

[Laa-Yosh]

Wow, I have learned programming a LONG time ago. Didn't even know there was a thing called Hungarian Notation

 

[sebbbi]

Hungarian Notation is an archaic notion from the days when your development environment and tools were practically worthless. From when you used simply text editors that could provide no insights into your code base. With modern day tools Hungarian Notation is entirely worthless at best and t worst it actually hinders the readability of the code.

Agreed 100%. Modern IDEs have robust auto-completion tools. Programmers do not need to remember interfaces or types anymore. When you type a dot after an identifier, auto-completion will also replace it with -> if the identifier was a pointer (= p/ptr prefixes are no longer needed). You can also quickly go to the definition of a variable by a single button press (actually it's alt+G in Visual Assist = two buttons). Visual Studio 2013 also has a new "peek definition" functionality that shows a few line text box howering on top of the code showing the location of the definition. Also when you mouse over an identifier, the IDE tells you the type of it. So basically there is no need to encode types to variable names anymore. It just makes reading harder and doesn't provide any real benefit (assuming of course that you name your identifiers so that they are understandable).

 

[Arwin]

I use peek definition a tonne, though most often as a quick way to get to a class to add a property. I am also a huge fan of refactoring. That said, I prefer my code to be readable and will append info to the name when improves readability, prefer to start parameters with lower case, etc. Semantically meaningful is the primary driver for me.