Jef Raskin (former Apple developer) has written a critique of the current state of Integrated Development Environments. He notes that programmers have been struggling with the same problems for 30 years, and although new IDEs have simplified many tasks, many are still a usability nightmare, noting, “most current IDEs make adding comments difficult, sometimes painful: You often have to wrap comments by hand, discouraging paragraph-length explanations, or at least discouraging their editing. It is incredible to see antediluvian interfaces in 21st-century products.”
How could an IDE make it easier to add paragraph length comments than just manually typing /* */?
This seems to be about design problems in IDE’s, or maybe about programming languages or open source development or the problems with getting started with programming or the lack of manuals.
Comments…..what are those. 😛
I love RAD. I really do.
But it is well nigh impossible to adequately comment code using a visual RAD interface. So, I have a solution.
RAD interfaces need to include “stickies” that act as comments that can be tied to visual controls. Methods of increasing usability could be making them semi-transparent and giving them little arrows that point to the controls that the comments refer to. THEN, as an added bonus, the source code for that control feature the sticky’s note in commented form.
Any bigwig IDE designers reading this?
I didn’t realize that the history of source code comments went back to before The Great Flood.
if my editor automatically wrapped commented lines to fit in the screen (and hopefully wrapped intellegently so that if the comment starts three tabs in, the wrap would accommodate) that would be so wonderful.
using /* */ is all fine, but you have to manually wrap it (meaning do hard returns at the end of the block) which is annoying when you would like to reflow it because of editting or changes.
I hope that kind of wrapping becomes standard.
When I was your age we had to….
=:-0
Since the Mosaic browser (circa 1992/93?)… things have been pretty stangnant revolution wise, eh?
Dictionary definition: Antediluvian – Extremely old and antiquated
Compilers are still in their infancy. How can I say this? Easy. Pointers. if compilers were mature we wouldn’t have to use pointers anymore. Compilers should be able to create the memory management on their own without programmers getting involved. Imagine how much more productive programmers could be if they just had to write the part of the program that doesn’t have anything to do with memory management.
No I’m not naive. I’ve been a programmer since 1979 working with many operating systems, programming languages, and hardware platforms. My first experience with C was in 1986.
While an intersting topic, I didn’t really get much out of it. Perhaps he is complaining of the use of text files as the basis of source code. Maybe we should all edit source codes in MsWord and we can use all kinds of cool pictures and graphs and styles. Not to mention clippy. Then we embed the source code in ‘code box.’ Run that through an preprocessor which extracts that code, and then though the compiler. No more /* */ or //, just beautiful word processor quality documents.
Of course, then you have portability concerns. Or perhaps things like windowing can be more self-documented. Instead of coding that when u click this menu item, that window opens, you implement that in the IDE (kinda like QT with certain signals). The IDE can then automatically generate some documentation and code.
In any case, I’m sure we’d all love to have MS embed VC++ code in Msword and Visio.
Yamin
that after 50 years of developing software people still don’t comment their F%$#ing code.
Big surprise, even if you made it such that people had to comment their code to make it run people would still think up ways to counteract that process.
Programming is not an product, it’s a process and we simply don’t have the tools to capture the processes we go through to generate the final product of code.
Just like you can’t capture the process of writing a book, only the finished content of a novel.
My programs are extensively documented. After each line I put : “// figure it out your own damn self”
“Just like you can’t capture the process of writing a book, only the finished content of a novel.”
Well maybe, but programming should be more like engineering than writing a book. I would be upset if my car broke and I had to find the designer of the car’s parts to be able to understand it, before they could fix it.
“Imagine how much more productive programmers could be if they just had to write the part of the program that doesn’t have anything to do with memory management.”
I love Java, too, but you could have just said it.
But, seriously, you’re confusing “compiler” with “language”. The kind of memory allocation design you’re talking about is a _feature_ of the language. If you don’t enjoy manually delete’ing your pointers, use a different language that’s designed to manage your memory for you.
In the distant future, I find it very likely that languages which force you to do manual memory deallocation will vanish.
-Erwos
The problem I think is that when the need for comments goes away, they’re still In The Way.
It’s simply the medium. While there are Literate Programming adherents out there, vast swaths of comments within source code really limit its readability (IMHO). The major reason I think that is that the primary reason for documentation is to describe the code. However, when you, the developer, already know what the code does (or have now learned it), all of the documentation becomes superfluous and simply gets in the way, particularly if it’s in the middle of a routine (versus outside of it).
A simple modern example is demonstrated by looking at well JavaDoc’ed Java source program. OMG!
Most editors and folks navigate their files through either searching or paging. For searching, if your search text is within a comment, you’re plonked in information that’s simply irrelevant to your task (assuming your task is not to learn the code), so you need to search again to get where you need to be. Same with paging through the source. Scrolling through reams of text that’s simply not important to you.
A lot of this can be overcome with smarter, more structure aware editors. Editors that make it easy to ellide and hide this documentation from your day to day working with the code.
Certainly such editors exist, but I don’t think they’re common in use, or at least these kinds of features are not commonly used.
How could an IDE make it easier to add paragraph length comments than just manually typing /* */?
What he’s referring to hear is simply that many program editors encourage typing long paragraphs of text.
In a generic word processor, design for runs of text that are wrapped to margins, even something as simple as this text box I’m typing in now, creating paragraphs is a mostly painless process. The rules for wrapping text and creating paragraphs are very simple.
With most source code editors, the word wrapping (if any) tends to get more in the way than of any actual help, so most users turn it off and hand wrap any of their lines of code that get too long. Hand wrapping an occasional line of code is no big deal, but hand wrapping paragraphs of text, particularly text that is being edited versus simply entered, is a pain in the neck. I typically end up just feed block of text to fmt(1), but it’s still a pain, and it discourages writing long comments.
Having a Sufficiently Smart Editor that Knows you’re within a comment block and can then switch on word wrapping, would be a large help. Most editors can identify and color a comment block, but few snap in to “text mode” when within one.
Of course, no doubt there are Emacs bits that implement all of this stuff.
The classical Smalltalk Browser pulled this off quite well. First, there is no single source file for the source code, you manage the code at the method level.
Second, the long missive about the code is in a seperate area away from the code (at least at a class level) and is available for ready reference. Whereas little hint like comments can still be embedded within the code itself.
The final problem is that comments are used for two things. User documentation (i.e. how to call the functions, etc), and implementation documentation (why it was written the way it was). Its difficult to keep these apart.
All of this can be solved with a combination of a Sufficiently Smart Editor and a structured file format, but since 99.99% of programmers basically edit a stream of bytes (as required by most languages), it’s a difficult issue to overcome for general cases.
I’m serious. It doesn’t hurt to learn what’s under the covers of that IDE, anyway.
After a development team thrashes about with religious wars over various IDEs, build tools, etc. what time is saved over using vi, make, and the Bourne shell? These old tools practically never fail, behave in known ways, and are a known quantity in a project with already too many unknowns. If vi is just too much, then use emacs (in viper mode, of course
.
“Most editors can identify and color a comment block, but few snap in to “text mode” when within one.”
If Microsoft implemented this, I would bet the embedded comment would be a proprietary comment format that is legible only in their IDE. Forget using a regular text editor after that. This would be almost as good as their proprietary “makefiles”.
Compilers are still in their infancy. How can I say this? Easy. Pointers. if compilers were mature we wouldn’t have to use pointers anymore. Compilers should be able to create the memory management on their own without programmers getting involved. Imagine how much more productive programmers could be if they just had to write the part of the program that doesn’t have anything to do with memory management.
I hate to break it too you but a compiler cannot do memory management at runtime. Just think about it, how is that possible? That’s the reason why you can’t create a dynamic array at runtime in C/C++, the size of the array must be known before runtime.
Now an external program that monitors your running application can – which is commonly known as a ‘virtual machine’. Now virtual machines have been around since since the mid 1970s. Lisp, Scheme, ML, Haskell, Java and Dylan are just a few examples. Even GCJ (compiled Java) has to use ‘libgcjgc’ for garbage collection and memory management.
“Most editors and folks navigate their files through either searching or paging. For searching, if your search text is within a comment, you’re plonked in information that’s simply irrelevant to your task (assuming your task is not to learn the code), so you need to search again to get where you need to be. Same with paging through the source. Scrolling through reams of text that’s simply not important to you.”
Increasingly in the Java community, editors are becoming smarter and no longer treat programs as text. For example, IntelliJ IDEA and Eclipse are competing in the general-purpose Java editor space (although I think that the Eclipse people really want to extend it to all languages). In IntelliJ, you can search for usages (on a semantic level), go to declarations, supers, etc. And you can navigate the code almost like a webbrowser (go back and forth between various points with certain key combinations). It understands block comments better (it doesn’t do auto-wrapping yet, though).
There are refactoring capabilities such as moving methods, renaming methods, extracting interfaces, etc. And they all operate on a structural level…not on a textual level.
Errors are underlined in red as they are introduced. There is a configurable setting on how long a period between keystrokes is necessary before the editor will start check for errors. I set it to half a second, and believe me, half a second after I do something dumb, it underlines it in red, even in large source files. There is no noticeable delay in responsiveness in the editor because of this. Compilation is incremental and fast. A full build of my 15kloc project takes less than ten seconds. And…I almost never get compile errors anymore, because I fix them as they are introduced.
This is the next logical step in editors, and for decent languages, these editors will eventually take over. Block comments…sure autowrapping would help, but the possibilities are so much more vast than that. I hope that there will come a day where code as text will be laughed at as a proven bad idea and all editors are structure based.
In my honest opinion, the most principal challenge that we face as technical people working to improve all software is dealing with (read that as junking, reengineering, or migrating) HUGE amounts of legacy code. Particularly C code.
C has this funny way of being everywhere. A C compiler for almost any platform exists. This isn’t anything inherent in the language (as compared to modern languages–perhaps to the languages of 1971 it was). This “everywhereness” has the funny effect that most people think that C is a decent platform to write software in….
But the truth is that C compilers vary wildly in quality, stability, and adherence to the unenforceable multitude of C language specifications. Several surprising but important parts (e.g. order of evaluation of arguments, operands, size and alignment of structs, interactions with unions) of the language are left unspecified, leading to a slow creep of many programs on undefined language semantics that is unnoticed due to the limited number of platforms and compilers that most applications were developed and tested on. Compiler bugs are less common but can be equally surprising (once identified).
Writing development tools for C that understand structure is difficult. The header file system, which relies on the most primitive idea of inlining the transitive closure of huge barfloads of tokens into a source file along with the standard pile of system header files that come laced with #ifdef’s and macros can quickly squash the spirits of any adventurous soul that wants to make a seriously clean, smart, and correct tool to do anything like what IntelliJ does (at least it did for me–I spent months thinking seriously about how such a system could work). Macros and the way some people use them throw a monkey wrench into the whole endeveaor…
That’s to say nothing of the weak type system of C and the way that most C programmers are encouraged to play dirty tricks in the name of efficiency long before the performance profile of the program stabilizes and is discovered through use of a decent profiler.
It’s not funny though….All desktop machines rely on huge amounts of C code that underlies their platforms in many many places. Everything from the kernel to the standard libraries to the windowing system to the virtual machine that runs their Java programs is written in C. All of the UNIX utilities are written in C. And even the efforts of the best of language designers and VM implementors eventually run on top of a huge amount of C code that is only stable because thousands of man years have found most of the memory leaks in the code that actually executes.
How many lines of C code will touch each of these characters I type? Or that you read?
Think about it. All those lines of C code need a compiler and toolchain. Those toolchains will ALWAYS be around while this code is in use. And guess what, while all of those toolchains are around, I can guarantee you that SOMEONE will think its a good idea to keep producing more and more C code for one poorly justified reason or another.
C has its uses. I will never dispute that C has its uses. Why can’t we make a decent language to replace C….FOR THOSE USES? Surely we can.
Until then, we’re kidding ourselves.
Meta-note: This didn’t start as a rant, but oh well.
Which was one of the things Jef raised on his article.
If you need paragraphs to document your code, then your code sucks!
Apparently you have never written a real program.
Perhaps I’m blind or just dense, but I didn’t see a reference to saving memory in the article.
OMG, while your message is totally off-topic, I can’t resist to comment on it a little …
“Compilers are still in their infancy. How can I say this? Easy. Pointers. if compilers were mature we wouldn’t have to use pointers anymore. ”
Pointers are features. And god damn useful features. I want pointers because the type of software I work on REQUIER me to manage my own memory and pointers.
Now explain to me how you can create a top-notch Operating System with a very specific memory management if the compiler does it for you ?
Long live C & C++.
“Imagine how much more productive programmers could be if they just had to write the part of the program that doesn’t have anything to do with memory management. ”
Since the ’70 you never heard of Object Oriented Programming ? With a good API and object tree, and a garbage collection, who cares about pointers for your high-level software ?
And don’t use the “I’m a programmer since the ’70” as my uncle fit this description, and he is up to this date the worst programmer with the worst habits I have ever met. In computer, being old school isn’t necessary a positive thing.
Increasingly in the Java community, editors are becoming smarter and no longer treat programs as text. For example, IntelliJ IDEA and Eclipse are competing in the general-purpose Java editor space (although I think that the Eclipse people really want to extend it to all languages). In IntelliJ, you can search for usages (on a semantic level), go to declarations, supers, etc. And you can navigate the code almost like a webbrowser (go back and forth between various points with certain key combinations). It understands block comments better (it doesn’t do auto-wrapping yet, though).
There are refactoring capabilities such as moving methods, renaming methods, extracting interfaces, etc. And they all operate on a structural level…not on a textual level.
And this kind of editor technology is exactly what I was talking about. There’s no reason why the editor must treat the source file as a “stream of bytes” instead of as an annotated syntax tree for the language. (Well, there is a simple basic reason: it can be very difficult to implement and do right.)
This kind of system can preserve the classic source code format (a stream of bytes in a file), which makes it compatable with other tools (notably the legacy compiler). As long as the editor doesn’t speckle editor tags and other cruft throughout the code for its own bookeeping, then it should be a friendly member in a mixed community.
This kind of system also demonstrates arguments against systems that rely on regular expressions vs true language parsers. Most syntax coloring systems work via regexps, but regexps have remarkably little context and minimal semantics, making them adequate for the lexing phase (which colored syntax essentially is), but worthless for anything else. They’re also difficult to extend into a more sophisticated parser style system, it’s usually better to just redo it from scratch.
Of course, regexps because of their simplicity are far more adaptable. It’s easier to convert regexps that color C code into regexps that color Java code, than to do the same with a C parser towards a Java parser.
I’m going to go look at IDEA, though, it sounds very interesting.
“If you need paragraphs to document your code, then your code sucks!”
Have you ever worked on a REAL software project ?
I remember writing a 2,000 line module for a complex LALR(1) math expression parser forming a cornerstone of a large software project. It contained a little over 1,000 lines of actual code. The other 1,000 lines were comments.
Because my code was so well commented, other coders were able to maintin my code without me ever having to look at it again.
Unfortunately, that meant they had no real reason to keep me around.
Anon
— Unemployed Software Engineer, Professional Code Commenter
I don’t believe in comments. I don’t use them. It was hard to write, so it should be hard to read
I don’t believe in comments. I don’t use them. It was hard to write, so it should be hard to read
And then someone finds a bug in the software and you can’t tell whether or not certain portions of your code are doing what you want since you can’t decipher your own program.
Many hundreds of ascii files are really constraining for developing, documenting, reviewing & providing full test coverage of code be it for SW projects or in my case for chip designs using C like HW description languages.
Besides the code itself, the copyright banners, revision header comments, the various types of code comments, research references, code review notes, the DTP documentation, web documentation, test plans, test suites, bug reports etc, are all highly interelated and I see them more as multiple views overlaid on a large multi document project. The grunt work of how fixing one view often propagates to fixing many other views across many many files to keep a project coherent. These views often straddle separate vendor tools, maybe separate version controls, usually multiple file formats and worse sometimes straddle different OS platforms and differnet owners.
I would love to see a single heterogenous database like approach for SW or HW projects where collaborating tools can filter the views you need/want to see. I think this is beyond the scope of a folding editor. The actual file granularity could be down to single functions, macros or modules etc, but doesn’t really matter. Your editor/browser could fake/present a subset of views to you per window with arbitary grouping, code ordering and filtering as you need such as by dependancies to/from a function.
Every change to any view would also have its own author attributions preserved so peers can more completely access/ review each others total work. Every view’s dependancies to other views would need some means to automate/assist propagating required edits and to manage exploding ToDo tasks.
I have found HW design environments mostly very primitive compared to SW IDEs but both could be much improved for better productivity and better cohesion of the project’s multiple views. Cadence developed something like this for chip designers but exchanging partial database tar files across sites was often fragile.
Brian N
Was this just an attempt to advertize Emacs? But anyway, all others: good luck with your IDEs. Can’t wait for you to catch up.
Why don’t the expensive, modern IDEs do what emacs could do decades ago, and do free of charge?
Sabon, many modern languages do away with pointers. The first example of this is Lisp. It’s had good garbage collection for decades now, and offers high-level programming with a minimal performance hit compared to Fortran and C (neither of which is high-level). Lisp is older than C, by the way, nearly as old as Fortran, and still the most modern language out there.
“Unfortunately, that meant they had no real reason to keep me around. ”
Well, a programmer that produce such quality AND commented code IS a good reason to keep you on board. At least in a world where managers act in a logical manner 🙂
A while a go I sumbled on a very funky looking editor (still in its infancy at the time, and kind of still born
), you coded in XML & the comment tags could contain any XML data, so you would have embeded HTML & SVG (while the editor did not display them correctly, it talked about a plugin system to let it).
It also (tried to) created the helper java-beans classes from the comments.
A while a go I sumbled on a very funky looking editor (still in its infancy at the time, and kind of still born
), you coded in XML & the comment tags could contain any XML data, so you would have embeded HTML & SVG (while the editor did not display them correctly, it talked about a plugin system to let it).
It also (tried to) created the helper java-beans classes from the comments.
Did this editor also come with the kung-foo grip?
Well, a programmer that produce such quality AND commented code IS a good reason to keep you on board. At least in a world where managers act in a logical manner 🙂
Unfortunately managers do not act in a logical manner. The fact is probably everyone posting here either 1) doesn’t comment at all or 2) doesn’t know what or how to comment.
The reason this is a topic is because we as programmers do NOT do it or do it badly. Face it when you are in the “groove” commenting is the last thing on your minds. Cranking out code is.
I have very rarely seen the need for paragraphs of comments. I have seen the need for programmers to use better variable names and better logic in their code.
Anyone that thinks comments aren’t necessary should revisit some of their code from as little as 1 year ago
& try to figure out what the program does. Chances are you’ll rewrite the entire thing from scratch because
you won’t be able to make head nor tail of it. Re: dynamic memory allocation, just what do you think malloc()/
calloc(), etc are doing? They allocate memory during runtime! Anybody that thinks otherwise should not be
allowed to post to this website, since they do NOT know what they’re writing about.
Here’s what I do…
Comment FIRST. I design my top level code, functions, or objects and comment those liberally so I know why I created them and what each is supposed to do. As I move through the actual lower level programming, most of the important documentation is finished.
The reason this is a topic is because we as programmers do NOT do it or do it badly. Face it when you are in the “groove” commenting is the last thing on your minds. Cranking out code is.
That is just a cheap excuse. You can very well be “in the groove” and still write good comments.
Of course it depends a little on what language you’re using, but in my experience you should hardly need comments.
Yes, I’m serious.
Take a look at this: http://ootips.org/comments.html :
“Comments are a sign of bad code in two ways. First of all, you add them to code that isn’t clear without them.
Good comments are comments that add clarity to code that isn’t clear or isn’t sufficiently clear without them.
There’s no point in belaboring the obvious or having a comment that fails to explain the nonobvious.
Now imagine taking a good comment and removing it. You are now left with code that is bad, or at least not as good as it could be.
In that limited sense, comments are a sign of bad code.”
Suffices to say that I totally agree.
Another nice piece on comments is the all-time favorite “How to write unmaintainable code” : http://mindprod.com/unmain.html
You know, there’s no reason why you can’t have an IDE where Emacs is the editor. Don’t remember any names, but they are out there
Cheap or not it is what is happening out there. That and the “I won’t comment so I am master of the code and they can’t fire me” attitude.
seen several people comment on idea now, and i cant just sit by without adding my plug.
quite simply, if you develop in java, use idea. refactoring is only the begginning, i have been using idea here at work for about 6 months now and i am still finding new features. my one and only complaint is the fact that there is zero javascript support, (i do webapps, which means JSP front end with craploads of js)
a few of my favorite features
mature refactoring
integrated source versioning, you can rollback to previous versions
incredable code completion, also, “Smart code completion” (ctrl-shift-space) which actually takes a guess based on the source paths, and is right a good 90% of the time.
auto importing. if you declair a variable whose type hasnt been imported yet, you hit alt-enter and a box pops up with the possible types. you select one and its imported for you.
code folding. gets around the messy look of a javadocd source file
ctrl-alt-t, the amazing “Surround With…” command. no easier way to add try/catch/finally
syntax coloring (of course) sytax error hilighting.
live templates. the most awesome use of macros in an ide i have ever seen. allows for variables, and they actually expose parts of the meta info of the source file to you, you get variables containing the class name, method name, line number, etc. once you create your macro, you give it a command. then type the command and hit tab, and it generates the code. for example, sop<TAB> will give me System.out.println(“”); (with my cursor inside the string), dbe will actually generates my generic catch-finally block for database interactions, req<tab> will give me request.getParameter(“”); on a jsp, etc…
i could go on and on. idea in my mind is the most modern ide i have ever seen, anyone frustrated by ide or editor limitations (who code java) owe it to themselves to check it out. best of all, its win/linux/osx, so you dont gotta worry about your workplace dev platform
“Unfortunately managers do not act in a logical manner.”
Don’t worry, I know my Dilbert 101 🙂
“The fact is probably everyone posting here either 1) doesn’t comment at all or 2) doesn’t know what or how to comment. ”
Most ? probably. Everyone ? I’m sure not. Personnally I’m a comment crazy. I think I comment very well all of my source, something I gratefully acquired working for my current employer.
“Face it when you are in the “groove” commenting is the last thing on your minds. Cranking out code is.”
The tempatation is always there. The trick is to develop a “Monica Geller” attitude toward code. In such a way that, when I finish a piece of code, if it’s badly commented, I start sweating, and then I just can’t live without commenting it. I just can’t. But that the end, this “obessession-compulsion” I developped is very positive.
“I have very rarely seen the need for paragraphs of comments. ”
Commenting well doesn’t mean commenting a lot. A very complicated function using some esoteric physics equations and tricky operations are better suited for paragraph-length comment. Beside those exception, one or two line is usually plenty enough.
“I have seen the need for programmers to use better variable names and better logic in their code.”
Oh ! So true … !!!
““I won’t comment so I am master of the code and they can’t fire me” attitude.”
Personnally I never witnessed such stupid behavior, and as far as I know, this is just a big myth.
“Cheap or not it is what is happening out there.”
Do not generalize. The two companies I worked for put a VERY big emphasis on comment. This is just a question of attitude : you think comment is a labor. I think a comment is as part of the code as a printf or a for() loop. Period.
> I have very rarely seen the need for paragraphs of comments.
> I have seen the need for programmers to use better variable
> names and better logic in their code.
Amen.