I was wondering what it requires to write a standard which targets programmers (e.g. JSON) and where to get started?
Does anyone has hands-on experience on that?
i think, a better question is, "how to write a good specification?" ...
most RFCs are bad specs, in my eyes ... personally, i quite hate them ... they are still better than ECMA-specs, but that's not a real criterium i think ...
for example: compare JSON-"specs" on json.org with the actual RFC ... i do agree, the first is not 100% exact (well, actually it is more exact then most JSON encoders), but in a few lines and a few syntax diagrams it says where JSON comes from, what its usage is, and defines the format ...
i don't see a real point in writing endless RCFs, because in the end noone reads them leading to the point where
you don't get the comment you requested for
people make implementations without really knowing your standard
if you really want to propose a standard, or make it comprehensible, do not use documents with countless pages ... it's just a waste of time ... when the standard is mature, you can start bothering making a very formal and strict definition, which is a good basis for highly consistent behaviour accross implementations, if it is really clear ...
do not obscure ideas by using too many strange and invented words, abreviations or refering to thousands of other things ... the simplicity of a solution is a measure for it's actual worth ... and treating the reader of your document, like a slightly dumb alien, to whom you have to explain everything, but at the same time expecting they can follow unjustifiably complex and bloated explanations, does not seem very sane to me ... just KISS ... ;)
The first thing you need is a community that need something. Then you need to get this community discussing.
Related
As I got a lot of spare time to spend ATM I read a few threads/comments on code-comments and documentation here.
As most people here I too think that you should write your code so that it's easy to read and self-commenting as far as it's possible.
On the other hand I am a huge FP-fanboy - and yes if you write your code the right way it will be very readable in FP - or so I thought.
Problem is that tiny things make a awful lot of difference in FP-world. If your colleague doesn't fully understand FP he might be able to "read" the indentation of the code but won't be able to modify or fully understand it. That stands for languagues like Haskell, where a '.' or '$' makes a big difference and also for languages like F# or even C# of VB.NET with lots of LINQ statements.
At first glance the problem might be, that your peer just doesn't get the language and it's not the codes fault - on the other hand: who truly gets all of FP? Look at some papers concerning Haskell - the code is beautifully crafted and self-commenting but just as in math you may have to chew on a line for several minutes before you get it.
Of course in those papers there will be a text-block trying to clarify just after the code ....
So IMHO you have to comment your FP-code as long as you work in a shop where not every colleague has a PhD in CS ;)
What do you think?
PS: first post here - really looked for answers concerning this questions but didn't find any - please be gentle if I just didn't look hard enough :)
Functional languages greatly favor the development of self-documenting code, because you can freely rearrange the order of functions, and easily abstract out any given part of the code, assigning it an explanatory name.
Abstract, abstract, abstract, is the keyword to master code complexity, and that's where the functional style shines. But there will be always things that cannot be expressed within the code itself.
One clear example is code for algorithms. It is unlikely that one can easily understand a complex algorithm just by looking at the implementation. Yes, functional languages make understanding simpler, becasue many gory details (trivial example: memory management) do not have to be coded explicitly, thus exposing the underlying logic more clearly.
However this is no substitute for an explanation in natural language, which conveys in an intuitive way how it works (and sometimes a picture is worth a thousand words). This is becasue our brain needs to observe difficult concepts from different point of views in order to understand them fully.
What to comment also depends on your audience. Beginners, average programmers or wizards? There is no one-fits-all solution.
E.g. you should explain the meaning of a "." (function composition) in Haskell if you are writing tutorial code, but certainly that would be a redundant explanation for anyone who has gone past chapter one/two of any Haskell book.
On the other hand some specific algorithm, like say red-black trees, could be a given for some programmers, and something very mysterious for others. In the second case you should add many comments to the code, or point to a document with further explanations.
Finally, one should notice that there is no consensus even among the masters. E.g. Dennis Ritchie is famous for being extremely parsimonious with comments, instead Don Knuth is an advocate of "Literate programming", where comments are as important as code itself. A set of rules will never be a substitute for personal taste.
Q:
Lately ,i asked for testing a code ,,to detect the bugs and fix the problems ,,i find many problems ,, but the main problem here is the code it self ,, spaghetti code many many code lines and the tracing to fix problems is so difficult ,, plus some code is copied and pasted from the internet as it is without any modification,, no documentation is possible to this code,,the performance is so bad due to the heavy using of viewstate in every thing,, and it takes me a lot of time to fix the problems ,, and iam afraid of after all this time still other bugs may appear in the future .. how to handle this case ,,any advices concerning this issue will be a great help.
Start refactoring. This will not make only the code better readable it will also give you a btter understanding on how it works and what it does.
That's a very common situation - software was developed for some years and by many different developers and now you have to support it. You should fight the will to throw it away and rewrite the whole application - it is a big effort and chances are big that you will do many mistakes that are already fixed in bad code. See Joel article for more explanations.
In my experience the best way is to refactor the code. However it involves writing a lot of tests - unit, automated acceptance - and it will take almost the same time as rewriting, but it will be less pain
I think the mentality for working with spaghetti code is summed up quite well in Refactoring by Martin Fowler.
The picture that comes to my mind is surgery: The entire patient except the part to be operated on is draped. The draping leaves the surgeon with only a fixed set of variables. Now, we could have long arguments over whether this abstraction of a person to a lower left quadrant abdomen leads to good health care, but at the moment of surgery, I'm kind of glad the surgeon can focus
Basically what that means is start small, and update a single part of the code at a time. Little changes will add up to good, structured code in the future.
Of course, if there are major problems with the entire architecture, you may have to heed Cybernate's advice and start from scratch (unpleasant as it may be).
I would also write unit tests as well as refactoring as codymanix said. This does a couple things:
As you refactor, you will have some check that your refactoring won't break things.
Writing the tests is a good way of learning the domain knowledge embedded in the code.
Of course, there is an inherent catch-22 with adding unit tests to spaghetti code: it is usually hard to unit test, and you need to refactor it to be able to make it testable. But if you go bit by bit and start with the low-hanging fruit, usually you can make it readable.
Scrap the existing code and start afresh.
That involves lot less effort comparitively.
If that's not a possible option start with Refactoring using tool like ReSharper that will give a good start.
Is it bad to be semantic purist all
the time, at work? is it not achievable all
the time ?
when i saw code of any other
person/interviewee. I know selection
of element for a purpose is most
important thing.
what i should judge person ability
from his code; from a good written,
managed, optimized css or how he
wrote class and id names?
Or both every time.
Is it bad to be semantic purist all
the time, at work? is it not
achievable all the time?
Yes. Sometimes the tools doesn't work the way that you would like, and you just have to use something that does work. It's worth a little effort to make the code more semantically correct to make maintenance more effective, but at some point you just can't defend the development cost because the gain in maintenance that it would give is a lot less.
what i should judge person ability
from his code; from a good written,
managed, optimized css or how he wrote
class and id names?
Anyone can have bad habits or incomplete knowledge in some areas. You should rather judge a person on the ability to see the difference between good and bad code when presented with it, and for showing a certain interrest in getting it right.
It depends on what you mean by "semantic purist".
Is his code so bad that you MUST refactor it first before you can do any maintenance on it or even be able to understand what the heck it does? Then it's important.
If the code is not perfect by your standards but udnerstandable, AND can be maintained, AND the person seems receptive to your hints about ways to improve it - especially if those hints are accompanied by explanation of why the improvement makes the code X% more readable/stable/maintainable, it's not THAT important what their level of "purity" is now.
If the person is willing to spend extra week polishing their code to be semantically pure at the cost of shipping late, he's a net loss by a big margin.
To give a specific example for css, if someone will add a class to EVERY element on a page just because it "should be added", bad.
If they indicate that the class needs to be added to places X, Y and Z so that jQuery selectors perform 20% better than alternative solution, VERY GOOD.
Both actually contribute to different abilities. A great abstraction design in Classes and Properties will depict his ability to analyze things where as a well writted managed optimized css expresses that he is himself/herself an organized person. The later property is also very important.
Still I will go for the first property if the css is atleast presentable.
Are you in danger of setting up a false alternative? We can either choose class and identifier names carefully or we can write working CSS? Ideally I'd prefer someone who can do both.
What do you deduce about the likely quality of a person's work if their job application has serious misspellings? Like the misspelling the name of the company they are applying to! What do you deduce about a project proposal that mis-states the objectives of the project? A person applying for a SW security job who confuses "authentication" and "authorisation".
In the interview you are trying to determine from a very small sample of information the likely way a person will perform if they come to work for you. We need to factor in many factors such as the effect of interview pressure on some folks performance, and whether they are working in their native language. I don't see any absolute standards here, and no scope for simple either-or questions such as you pose.
Of course we need them to be able to produce code that works, that's the easy bit! Quality of code, and quality of other aspects of work also do matter.
I have recently been put in charge of debugging two different programs which will eventually need to share an XML parsing script, at the minimum. One was written with PureMVC, and another was built from scratch. While it made sence, originally, to write the one from scratch (it saved a good deal of memory, but the memory problems have since been resolved).
Porting the non-PureMVC application will take a good deal of time and effort which does not need to be used, but it will make documentation and code-sharing easier. It will also lower the overall learning curve. With that in mind:
1. What should be taken into account when considering whether it is best to move things to one standard?
(On a related note)
Some of the code is a little odd. Because the interpreting App had to convert commands from one syntax to another, it made sense to have an interpreter Object. Because there needed to be communication with the external environment, it made more sense to have one object interact with the environment, and for that to deal with the interpreter exclusively.
Effectively, an anti-Singleton was created. The object would only interface with the interpreter, and that's it. If a member of another class were to try to call one of its public methods, the object would raise an Exception.
There are better ways to accomplish this, but it is definitely a bit odd. There are more standard means of accomplishing the same thing, though they often involve the creation of classes or class files which are extraordinarily large. The only solution which I could find that was standards compliant would involve as much commenting and explanation as is currently required, if not more. Considering this:
2. If some code is quirky, but effective, is it better to change it to make it less quirky, even if it is made a more unwieldy?
In my opinion this type of refactoring is often not considered in schedules and can only be done when there is extra time.
More often than not, the criterion for shipping code is if it works, not necessarily if it's the best possible code solution.
So in answer to your question, I try and refactor when I have time to do so. Priority One still remains to produce a functional piece of code.
Things to take into account:
Does it work as-is?
As Galwegian notes, this is the only criterion in many shops. However, IMO just as important is:
How skilled are the programmers who are going to maintain it? Have they ever encountered nonstandard code? Compare the cost of their time to learn it (including the cost of delayed dot releases) to the cost of your time to refactor it.
If you're maintaining it, then instead consider:
How much time will dealing with the nonstandard code cost you over the intended lifecycle of the codebase (e.g., the time between now and when the whole thing is rewritten)?
That's hard to guess, but consider that many codebases FAR outlive the usefulness envisioned by their original authors. (Y2K anyone?) I've gradually developed a sense of when a refactoring is worthwhile and when it's not, mostly by erring on the side of "not" too often and regretting it later.
Only change it if you need to be making changes anyway. But less quirky is always a good goal. Most of the time spent on a particular piece of software is in maintenance, so if you can do something to make that easier, you'll be reducing the overall time spent on that piece of code. Nonetheless, don't change something if it's working and doesn't need any modifications.
If you have time, now. If you don't have time and it can be avoided, later.
Closed. This question is opinion-based. It is not currently accepting answers.
Closed 3 years ago.
Locked. This question and its answers are locked because the question is off-topic but has historical significance. It is not currently accepting new answers or interactions.
I have been working on a list for a while that helps me share the why of programming approach and thought as much as how to do something.
For this, I wanted to build a list of things that are:
best practice,
best thought,
best approach...
that help a programmer's ability to analyze, think, approach, solve and implement in the most effective way.
I have seen dozens of incredibly valuable comments in questions throughout Stack Overflow, but I couldn't find a place where we keep them together. There is the most controversial opinion on Stack Overflow. However, I'm just looking for sagely insights that can be shared and help my team, and I approach and solve problems better through better programming.
Hopefully this can be one place to gather the one or two liners that are concise, profound and easy to share, repeat, review. If we keep it to one rule per answer it might be easiest to vote up/down.
I'll start with the first.
DRY - Don't Repeat Yourself - In code, comments or documentation.
Always leave the code a little better than when you found it.
Code does not exist until entered into a versioning control system.
Don't be afraid to admit "I don't know" and ask.
10 minutes asking someone could save a day pulling your hair out!
KISS - Keep it simple, stupid.
Pick the simplest solution that works.
Don't make things (too) complicated before they need to be.
Just because everyone else is using some complicated framework to solve their problem, doesn't mean you have to.
Don't reinvent the wheel
If there ought to be a function for it in the core library - there probably is.
Maintainability is important.
Write code as if the person who will end up maintaining it is crazy and knows where you live.
Someone else won't fix it.
If a problem comes to your attention, take ownership long enough to ensure it will be taken care of one way or another.
Don't optimize unless there's a demonstrable problem.
Most of the time when people try to optimize code before it's been proved necessary, they'll spend a lot of resources, make the code harder to read and maintain, and achieve no noticeable effect. Sometimes they'll even make it worse.
"We should forget about small efficiencies, say about 97% of the time: premature optimization is the root of all evil."
- Donald Knuth
How hard can it be?
Don't let any problem intimidate you.
Don't Gather Requirements -- Dig for Them
Requirements rarely lie on the surface. They're buried deep beneath layers of assumptions, misconceptions, and politics
via The Pragmatic Programmer
Follow the SOLID principles:
Single Responsibility Principle (SRP)
There should never be more than one reason for a class to change.
Open-Closed Principle (OCP)
Software entities (classes, modules, functions, etc.)
should be open for extension, but closed for
modification.
Liskov Substitution Principle (LSP)
Functions that use pointers or references to base
classes must be able to use objects of derived classes
without knowing it.
Interface Segregation Principle (ISP)
Clients should not be forced to depend upon interfaces
that they do not use.
Dependency Inversion Principle (DIP)
A. High level modules should not depend upon low
level modules. Both should depend upon abstractions.
B. Abstractions should not depend upon details. Details
should depend upon abstractions.
Best Practice: Use your brain
Don't follow any trend/principle/pattern without thinking about it
I think almost everything that is listed under "The Zen of Python" applies for every "Rules of Programming Mindset" list. Start with 'python -c "import this"':
The Zen of Python, by Tim Peters
Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than right now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!
Test Driven Development (TDD) makes coders sleep better at night
Just to clarify: Some people seem to think TDD is just an incompetent coder's way of limping from A to B without borking everything up too much, and that if you know what you're doing, that means there is no need for (unit) testing methodologies. That completely misses the point of Test Driven Development. TDD is about three (update: apparently four) things:
Refactoring magic. Having a full set of tests means you can make otherwise insane refactoring stunts, juggling the entire structure of your application without missing even one of the two hundred crazy subtle side effects that result from it. Even the best programmers are reluctant to refactor their core classes and interfaces without good (unit) test coverage, because it's damn near impossible to track down all the little 'ripple effects' it causes without them.
Detecting pitfalls early. If you are writing tests the right way, it means forcing yourself to consider all the fringe cases. Often, this leads to better design choices once the actual development begins, because the coder has already considered some of the trickier situations that may call for a different inheritance structure or a more flexible design pattern. The need for these changes is often not apparent - or intuitive - during initial planning and analysis, but those exact changes can make the application much easier to extend and maintain down the line.
Ensuring that tests get written. TDD requires you to write the tests before writing the code. Sure, that can be a pain in the ass, since writing tests is tedious compared to writing actual code - and often takes longer, too. However, doing so is the only way to make sure the tests will be written at all. If you think you'll remember to write the tests once the code is done, you're almost always wrong.
Forcing you to write better code. Since TDD forces all code to be testable (you don't write code before there is a test for it), it requires you write more decoupled code so that you can test the components in isolation. So TDD forces you to write better code. (Thanks, Esko)
Google before you ask your colleague and interrupt his coding.
Less code is better than more, as long as it makes more sense than lots of code.
Habits of the lazy coder
The first time you are asked to do something, do it (right).
The second time you are asked to do it, make a tool that does it automatically.
And the third time, if the tool doesn't cut it, design a domain specific language for generating more tools.
(not to be taken too seriously)
Be a Catalyst for Change
You can't force change on people. Instead, show them how the future might be and help them participate in creating it.
via The Pragmatic Programmer
Don't Panic When Debugging
Take a deep breath and THINK! about what could be causing the bug.
via The Pragmatic Programmer
You may copy and paste to get it working, but you may not leave it that way.
Duplicated code is an intermediate step, not a final product.
It's Both What You Say and the Way You Say It
There's no point in having great ideas if you don't communicate them effectively.
via The Pragmatic Programmer
Always code as if the person who ends up maintaining your code is a violent psychopath who knows where you live.
From: Coding Horror
Build Breaker Buys Lunch
Publish Early, Publish Often
Build it correct first. Make it fast second.
Frequently conduct code reviews
Code review and consequently refactoring is an ongoing task. Here is a few goodies about code review in my opinion:
It improves code quality.
It helps refactor reusable codes into reusable libraries.
It helps you learn from your fellow developers.
It helps you learn from your mistakes and refresh your memory about a genius code you have written before.
Anything that could affect how the application runs should be treated as code, and that means putting it in version control. Especially build scripts and database schema and data (.sql) files.
Take part in open source development
If you are using open source code in your projects, remember to post your bugfixes and improvements back to the community. It's not a development best practice per se, but it's definitely a programmer mindset to strive for.
Understand the tools you use
Don't use a pattern until you've understood why you're using it; don't use a tool without knowing why; don't rely on your framework or language designer always being right for your situation, but also don't assume they're wrong until proven to be!
Convention over Configuration
Especially where conventions are strong and some flexibility can be sacrificed.