Effective and practical documentation captures the intended use of modules, classes and routines in a user-manual-like form. In order to produce highly maintainable documentation, practice indicates that comments should not focus on explaining how the code works, but rather on how the code is to be used.
If comments are used to explain how the code works, any alteration to the code will render the documentation obsolete, resulting in duplication of effort and inaccurate documentation.
Plain English at the top of the file and each code construct should be used to describe its unique purpose and objective. Inline, detailed comments should be avoided because they cannot express the mechanics of the code more accurately than the code itself.
By avoiding the description of "anything between the brackets", the formal documentation reaches the non-redundant level of abstraction needed to streamline the authorship, usage and maintenance of the code.
That is bull. "Talented developers" in a big organization? Well established processes are the only factor that counts, so every developer can be replaced, like lego pieces. Otherwise organizations would be relying on individual talent, that is Ok in a 5 people team, but not for big software. Maybe this is the reason why MS software didn't shine for a long time. Now it is a lot better. I use it myself.
Actually, I don't like the new design. It is retrograde and it does not advance the concept, nor it makes it more attractive for people to feel compelled to download the product. The previous design used shades of color and well placed logos that conveyed a serious, modern/future-is-here, unique, and time-tested product. The current design is simpler and not as rich. It remains me of a 3/4 year old RedHat 8/9 desktop.
Not buying there anymore in 4 acts.
on
Best Buy Sued By Ohio
·
· Score: 2, Informative
ACT 1: I bought a LCD monitor and I got my credit card checked "for my own security" because the purchase was over 500CND. I felt like walking out, but I tolerated the insult.
ACT 2: I paid a small item with my ATM card. The cashier girl uses a plastic bag as a glove to receive the card and swipe it. She looked like a uptight doll.
ACT 3: I was told that the 4th gen iPod and iPod mini will be released in mid October. So I should buy the will-never-sell-stocked 15GB 3rd gen iPod instead, and now.
FINAL ACT: Took from the shelf an audio card with a pricing clearly marked. Went to pay for it; it is 40 dollars more. Then I am told that "it must be a mail in rebate available for it". I left the item there and I walked to never enter again.
1. Get 100, equal webcams 2. Put in an array of 10x10 3. Feed input to several computers (USB) 4. Apply respective parallel image processing, including mosaic techniques that will get rid of overlap 5. Feed resulting data to a single computer 6. Play with the resulting ~30 Mpixel image.
Don't forget to point it to the sky. You may arrange things so you have complete sky coverage, then track aircraft and meteors. Adjust software accordingly.
It was clear, even back in 1995, that this file navigation paradigm didn't work. I was astonished to see it implemented in Gnome 2.6. For me Gnome has been rendered unusable. The author of the article lengthly explains how he has to re-organize his world just to accommodate the new changes. This is disgraceful; even a child is able to navigate files a la explorer way. Nice and convenient way to break a very viable platform for Linux desktop applications. The issue for me is that I won't use Trolltech's billboard (KDE).
Yes, in Chile, Vim is a thick clear greenish liquid use to do your dishwashing, like Palm Olive here in North America. Maybe this is a related P&G stuff.
Today I spent the whole day trying to parse a 2M plain text document using the regular expressions feature in Java 1.4. I could not get anything done, the thing just crashes. I wanted a "portable" solution very dearly, and I wanted to "do" Java. Sorry, but, like every other time, it just doesn't work. I bought all these books; I really like Java. I just can't get anything done with it in a reliable way without recurring to some sort of trick, or following some "the right way to do Java" advise/book/article. I have not tried other solutions, like Perl or Python, but I am not taking any risks; I'll just settle for C++ and plain finite state machines for now. Nothing better than a tool that works well every time.
In our work environment, we use Citrix on top of HP-UX. In general, it is slow and the only applications available are Word, Excel, and FrameMaker. The mouse scroll wheel is not supported and employees cannot install software on the served Windows environment. Surely I imagine this must be paradise for IM.
When frustration peaked, they installed a real Windows box besides our HP360, so we ended up with 2 systems; it is cumbersome, but it works.
In my view, all this could be replaced with a single Linux box, OpenOffice added, plus any additional application you might require on top.
I use the common denominator; limited CSS1, tables and hand coding to get exactly what I want. I test in IE, Gecko, and Opera. No issues. The Visibone color palette is the safest (your colors will look the same in 16, 24, or 32 bit color.). Test all your color gradients to ensure they look smooth in 16 bit color.
Re:Mono - the most un-quirky yet
on
Mono 2.8 Released
·
· Score: 2, Insightful
I am sure you where joking, but if you truly favor the death penalty, then it is clear that you need a couple of lives more, at least, for self-realization, I mean:)
I have the greatest respect for the work that Bill Gates and MS have done and continue doing; MS has revolutionized the way we compute. Today, computers are in hour houses and companies, featuring effective interfaces, powerful programming languages and developing environments. I believe new developments, like.NET languages and framework are welcomed by everyone, since they represent the evolution of computing, and not only that; these products are presented as a consistent framework that is clear and easy to use, with some issues, but great all around.
What I don't like about a market economy and innovation these days is the rate at which products are launched, plus the upgrading as a commercial strategy for revenue. It is possible to produce at near zero defect quality, with some constraints, but companies and people don't bother anymore. I see this trend in software of course, but also in other industries, like in the music and movie industry. Quality is getting lost to favor a quick product. Not labors of love and craftsmanship, like a Stanley Kubrick film, but quick montages to quickly satisfy a need and to get something out in the market.
I have always said that the only open source projects that are successful are the ones that have a powerful vision behind, plus financing. Founding is essential since, due to our nature and for the project own sake. Founding obligates project leaders and developers to follow a well defined process, to commit to a plan or schedule and to effectively see the product happen.
Now Mono. Mono looks from the outside like an impressive piece of software. The development process looks exceptionally well organized and their lead developers exceptionally skilled. Good for Mono! If implemented completely (no doubt) it will be a very useful product since we'll benefit from the well crafted MS development tools and ideas.
We live in the real world, and you cannot simply expect that there is ZERO commercial interest in a development of the magnitude of the.NET framework. I would make no sense, as it makes no sense that the most successful company in the planet wouldn't have *any* interest in the parallel development of their technologies. *I have no proof of this*, but I, myself would be interested if placed in MS feet.
Finally I would like to say that the best work I have seen comes without any doubt, from young people when they are guided correctly, like university students, especially in their initial years. No matter if rich or poor, they believe in what they do. That is the spirit that has bootstrapped the open source movement and that still somehow impregnates it.
I simply resist the idea that Mono is a labor of love ala "tunnel vision", "must-be-done" project. Icaza no seria muy inteligente si trabajara gratis como estudiante universitario de primer year para la mayor multinacional del planeta, no crees?
Mono is a product pushed and financed by Microsoft. Mono is somehow their last line of defense, a marketing device and a legitimacy tool. C# and friends have not been able to take off as intended simply, hype aside, because it is not a practical tool to develop end user software (for in-house projects it does well it seems). C# is a work in progress, meaning core updates are coming for at least two or more product generations.
What software designers want is a stable, un-quirky framework to develop applications, even if it is not fancy, not a bag full of tricks and weird behavior, hence the success of Delphi, Ansi C/C++ and even old Visual Basic (at least they know where the quirkiness is by now).
Since computers are universal machines, why do you need so much language refinements when a well chosen instruction set ala RISC is all we need.
Not for me, I have been using English only for a few years and I had absolutely no trouble reading the counterexample paragraph (my native language uses western characters).
This is funny, someone must be very afraid to kill an oil dependent economy. The technology has been here for long time; electric, hydrogen, natural gas, wind, solar, etc. yet no politician or development plan will commit to this seriously, not even for public transportation. This is a can of worms that goes well beyond the automotive industry; at least they are trying to improve thanks to Japan's hybrid cars.
The problem with XML in comments is that it is intrusive. XML was intended to be readable to machines first, then to humans. Java tags are better, but still they are not an ideal solution. There are some commercial documentation tools, like TwinText, that analyze plain text comments and generate useful documentation from them.
This article is irrelevant and not an appropriate choice for Slashdot. It focuses in one individual (who is he?) and his "experience" while transitioning or probing the Linux waters. There is no contribution here.
Yesterday I purchased the last CD from Radiohead. Besides the perceived musical involution, I noticed that I *could not* play the CD in my computer ("files needed to be modified first"). I now, this isn't new, but this is the first time for me. I think this is the last time I buy a music CD. Downloaded music is much better; it saves space, it it cheap, I get what I want and I can play the music everywhere.
This also may explain why time travel seems impossible: we dont meet visitors from the future since only the present is being simulated.
Nope, the reason time travel is impossible is that a simulation is irreversible. The only way to see the future is by running the simulation. The only way to see the past is by storing snapshots of the simulation. Just the way we do it. CA 101.
Slashdot Mirror
Commenting Code
Effective and practical documentation captures the intended use of modules, classes and routines in a user-manual-like form. In order to produce highly maintainable documentation, practice indicates that comments should not focus on explaining how the code works, but rather on how the code is to be used.
If comments are used to explain how the code works, any alteration to the code will render the documentation obsolete, resulting in duplication of effort and inaccurate documentation.
Plain English at the top of the file and each code construct should be used to describe its unique purpose and objective. Inline, detailed comments should be avoided because they cannot express the mechanics of the code more accurately than the code itself.
By avoiding the description of "anything between the brackets", the formal documentation reaches the non-redundant level of abstraction needed to streamline the authorship, usage and maintenance of the code.
http://www.ptlogica.com/TwinText/paper.htmThat is bull. "Talented developers" in a big organization? Well established processes are the only factor that counts, so every developer can be replaced, like lego pieces. Otherwise organizations would be relying on individual talent, that is Ok in a 5 people team, but not for big software. Maybe this is the reason why MS software didn't shine for a long time. Now it is a lot better. I use it myself.
Actually, I don't like the new design. It is retrograde and it does not advance the concept, nor it makes it more attractive for people to feel compelled to download the product. The previous design used shades of color and well placed logos that conveyed a serious, modern/future-is-here, unique, and time-tested product. The current design is simpler and not as rich. It remains me of a 3/4 year old RedHat 8/9 desktop.
No further comments.
ACT 1: I bought a LCD monitor and I got my credit card checked "for my own security" because the purchase was over 500CND. I felt like walking out, but I tolerated the insult.
ACT 2: I paid a small item with my ATM card. The cashier girl uses a plastic bag as a glove to receive the card and swipe it. She looked like a uptight doll.
ACT 3: I was told that the 4th gen iPod and iPod mini will be released in mid October. So I should buy the will-never-sell-stocked 15GB 3rd gen iPod instead, and now.
FINAL ACT: Took from the shelf an audio card with a pricing clearly marked. Went to pay for it; it is 40 dollars more. Then I am told that "it must be a mail in rebate available for it". I left the item there and I walked to never enter again.
We test on:
- Internet Explorer
- Mozilla and siblings
- Opera
For us this works very well.7. Play also with the potential 3D scene that you can generate, including accurate distance measuring, between all elements of the captured scene :)
1. Get 100, equal webcams
2. Put in an array of 10x10
3. Feed input to several computers (USB)
4. Apply respective parallel image processing, including mosaic techniques that will get rid of overlap
5. Feed resulting data to a single computer
6. Play with the resulting ~30 Mpixel image.
Don't forget to point it to the sky. You may arrange things so you have complete sky coverage, then track aircraft and meteors. Adjust software accordingly.
There are not many alternatives left.
Yes, in Chile, Vim is a thick clear greenish liquid use to do your dishwashing, like Palm Olive here in North America. Maybe this is a related P&G stuff.
Today I spent the whole day trying to parse a 2M plain text document using the regular expressions feature in Java 1.4. I could not get anything done, the thing just crashes. I wanted a "portable" solution very dearly, and I wanted to "do" Java. Sorry, but, like every other time, it just doesn't work. I bought all these books; I really like Java. I just can't get anything done with it in a reliable way without recurring to some sort of trick, or following some "the right way to do Java" advise/book/article. I have not tried other solutions, like Perl or Python, but I am not taking any risks; I'll just settle for C++ and plain finite state machines for now. Nothing better than a tool that works well every time.
When frustration peaked, they installed a real Windows box besides our HP360, so we ended up with 2 systems; it is cumbersome, but it works.
In my view, all this could be replaced with a single Linux box, OpenOffice added, plus any additional application you might require on top.
You cannot sell products written in Java or C#, period. In-house stuff, yes, no problem there. Still I would use Python or Perl instead.
I use the common denominator; limited CSS1, tables and hand coding to get exactly what I want. I test in IE, Gecko, and Opera. No issues. The Visibone color palette is the safest (your colors will look the same in 16, 24, or 32 bit color.). Test all your color gradients to ensure they look smooth in 16 bit color.
I have the greatest respect for the work that Bill Gates and MS have done and continue doing; MS has revolutionized the way we compute. Today, computers are in hour houses and companies, featuring effective interfaces, powerful programming languages and developing environments. I believe new developments, like .NET languages and framework are welcomed by everyone, since they represent the evolution of computing, and not only that; these products are presented as a consistent framework that is clear and easy to use, with some issues, but great all around.
What I don't like about a market economy and innovation these days is the rate at which products are launched, plus the upgrading as a commercial strategy for revenue. It is possible to produce at near zero defect quality, with some constraints, but companies and people don't bother anymore. I see this trend in software of course, but also in other industries, like in the music and movie industry. Quality is getting lost to favor a quick product. Not labors of love and craftsmanship, like a Stanley Kubrick film, but quick montages to quickly satisfy a need and to get something out in the market.
I have always said that the only open source projects that are successful are the ones that have a powerful vision behind, plus financing. Founding is essential since, due to our nature and for the project own sake. Founding obligates project leaders and developers to follow a well defined process, to commit to a plan or schedule and to effectively see the product happen.
Now Mono. Mono looks from the outside like an impressive piece of software. The development process looks exceptionally well organized and their lead developers exceptionally skilled. Good for Mono! If implemented completely (no doubt) it will be a very useful product since we'll benefit from the well crafted MS development tools and ideas.
We live in the real world, and you cannot simply expect that there is ZERO commercial interest in a development of the magnitude of the .NET framework. I would make no sense, as it makes no sense that the most successful company in the planet wouldn't have *any* interest in the parallel development of their technologies. *I have no proof of this*, but I, myself would be interested if placed in MS feet.
Finally I would like to say that the best work I have seen comes without any doubt, from young people when they are guided correctly, like university students, especially in their initial years. No matter if rich or poor, they believe in what they do. That is the spirit that has bootstrapped the open source movement and that still somehow impregnates it.
Regards.
I simply resist the idea that Mono is a labor of love ala "tunnel vision", "must-be-done" project. Icaza no seria muy inteligente si trabajara gratis como estudiante universitario de primer year para la mayor multinacional del planeta, no crees?
What software designers want is a stable, un-quirky framework to develop applications, even if it is not fancy, not a bag full of tricks and weird behavior, hence the success of Delphi, Ansi C/C++ and even old Visual Basic (at least they know where the quirkiness is by now).
Since computers are universal machines, why do you need so much language refinements when a well chosen instruction set ala RISC is all we need.
Not for me, I have been using English only for a few years and I had absolutely no trouble reading the counterexample paragraph (my native language uses western characters).
This is funny, someone must be very afraid to kill an oil dependent economy. The technology has been here for long time; electric, hydrogen, natural gas, wind, solar, etc. yet no politician or development plan will commit to this seriously, not even for public transportation. This is a can of worms that goes well beyond the automotive industry; at least they are trying to improve thanks to Japan's hybrid cars.
The problem with XML in comments is that it is intrusive. XML was intended to be readable to machines first, then to humans. Java tags are better, but still they are not an ideal solution. There are some commercial documentation tools, like TwinText, that analyze plain text comments and generate useful documentation from them.
This has to be the most irrelevant story ever published here. Specially if coming from CowboyNeal.
Today HD space is hardly an issue
Nobody uses Win95
If you want to embed Win95, please visit your psychiatrist first
This article is irrelevant and not an appropriate choice for Slashdot. It focuses in one individual (who is he?) and his "experience" while transitioning or probing the Linux waters. There is no contribution here.
Yesterday I purchased the last CD from Radiohead. Besides the perceived musical involution, I noticed that I *could not* play the CD in my computer ("files needed to be modified first"). I now, this isn't new, but this is the first time for me. I think this is the last time I buy a music CD. Downloaded music is much better; it saves space, it it cheap, I get what I want and I can play the music everywhere.
Shareware = Try before you buy
A tryout for 30 days is the industry standard(Microsoft, Corel, etc.). âoeSharewareâ has always been âoealiveâ.
This also may explain why time travel seems impossible: we dont meet visitors from the future since only the present is being simulated.
Nope, the reason time travel is impossible is that a simulation is irreversible. The only way to see the future is by running the simulation. The only way to see the past is by storing snapshots of the simulation. Just the way we do it. CA 101.