I have worked a few places which haven’t used source control. They seemed to get into the habit of putting comments around code they changed explaining the change so that things could be reverted.
I have found that this makes the code very difficult to read, and have been fairly adamant that such comments are not needed after introducing source control as the revision history will let you match up tickets with changes.
However now, I am not so sure, I think it may be good to document major revisions to a file in a file as well as in the commit messages. This should make the code more readable. Do people have a best practices way of documenting changes to code, so that it is not too cluttered but is still explanatory to someone trying to read it?
Just to be clear, I am not talking about a list of changes in the head of the file (which is a whole other argument) but comments in the code.
Most source control systems have an "Annotate" or "blame" command. It shows what code changed with each revision.
Since this information does not change the behavior of the program, or make it easier to understand the program, it doesn't belong in the program.
The documentation present in code should describe the code it is near. If the code changes, the documentation should also change accordingly. The version control system should take care of managing what changed and why it changed. Let the code and it's documentation do it's job (Doing things, and describing how/why those things are done), and let the version control system do it's job (controlling/documenting versions and changes).
Whenever you start indicating history in the present(current code), you are asking for trouble. Just think what a particularly change-heavy area of code would look like if it had a number of changes?!
If the comment is time sensitive don't do it it's a bad idea. Put a comment on the source file in the version control system instead.
I see this problem all the time at work. The code base I am currently working on extends back to 1979. You can imagine the difficulty with comments like the one below which have built up over that time:
"Line below seems to fix bug xyz, will revert if unforseen issues occur"
I realise it's not a very descriptive comment in the first place but that sort of thing in svn/cvs/etc. is actually very handy. A comment like that in the code sows the seeds of doubt. Can the comment be removed? Is the unforseen issue that has caused me to have to look back at the code related to this comment? etc.
I'm just wondering how knowing what the program USED to do helps understanding it now? You say it aids readability. How?
Now, when something is changed because the old way didn't work and the new way is counter-intuitive, I think that should be commented in code, because it's necessary to know for all time "This didn't work, don't do it again. I know it looks like it would make more sense. Still don't do it." Otherwise, I don't see that it helps.
Don't think that commenting changes inside a code is ever possible in a explanatory way.
But I'd like to say about "Modification history at the file begin". I doubt that this is useful at all. Unless I wanted to know which to versions of a file to compare to see the difference that were introduced with some "NNNN" task. In the file begin there is a line "NNNN date - small description". And our source control can "say" who and in which version this line was introduced.
So without this line I would look through all versions to find correct one.
I think it's good to document major changes or refactorings as comments in the code. I agree that it does get a little messy to read around copious amounts of comments, but I think it's easy enough to ignore the comments and try to just read the code. If anything is confusing, or you are tempted to change something, and there is a comment near by, you will be much more inclined to read the comment, as opposed to doing diffs with previous versions to see what had changed and why.
Each method in our codebase has its own change history. When the code of a method is changed its header gets a new entry. The code itself does not get cluttered with history comments, only the method header. Each change history entry consists of one or two lines briefly describing the reason for the code change in general terms. The entry also contains a number that refers to a change document, The change document also contains links to bug reports, development projects, design documents etc.
Such entries are invaluable, as they often give you an insight as to why the code is as it is. If you are there to fix a bug the history trace will invariably tell what code change introduced the bug, what the change was attempting to do, and therefore what else you need to be aware of when deciding on a fix.
OTOH - Reams of comments in the body of the code describing what it does and who changed it when are just noise.
Going to have a stab at answering this myself.
Documenting every change in the source makes it difficult to read, however if there is a particularly counterintuitive piece of code in there and it was introduced for a particular ticket put a note by it as to why the code is strange.
But the code should still be documented. So while you make not put in
/* ticket 101: add blink tag to headers, JF - 20010102 */
You may want to put in
/* make headers blink */
Quite often when people stop doing the former type of comments, they cut down massively on their comments and this is bad.
Related
This is the first time I am trying to contribute to Mozilla. I went through several articles and documentation/resources to get a hang of what could be the best first steps to get started. I started off from this page http://whatcanidoformozilla.org1 and chose to start off with Java.
On initial tinkering I was taken to https://wiki.mozilla.org/Mobile/Get_Involved and eventually https://wiki.mozilla.org/Mobile/Fennec/Android/Suggested_workflow resource suggested that the best way to get started with it would be to pick up some simple bug and propose a patch for it.
So then I went to http://www.joshmatthews.net/bugsahoy/?java=1&simple=1 and this specific bug drew my attention. The description of the bug mentioned this :
There are some methods that we share (or can share) across our DB
implementations, like appending PARAM_SHOW_DELETED, PARAM_LIMIT, or
PARAM_PROFILE.
These are currently spread across LocalBrowserDB, TabsAccessor,
URLMetadata, and so on. It'd be nice to clean these up.
Question 1. Now how do I get some more context on what exactly is the bug and what is required to be done ?
As of now there seems to be 2 patches already submitted from what I understood (and please correct if my understanding is wrong here). So to get some context about the bug I went ahead and opened up the first patch submitted here.
It gave me some idea as to at least where exactly is the code itself that needs to be fixed. And I found it here
Question 2. Am I on the right track on how to figure out the code that needs to be fixed ?
Question 3. Even after reaching the DBUtils.java file I could not find any documentation about what the class basically does, or where does it fit into the whole picture. Could someone please help me with this, as to how do I figure out what a class is supposed to be doing etc. or at least some documentation around it?
You're on the right path. Basically, the What Can I Do For Mozilla website is a quick and easy way to let you discover projects you might be interested in, so it's the first gateway to the coding contributions.
That said, you did good in picking a bug to start off. However, as you saw the bug was already being worked on by somebody else (marked as Assigned). Your best bet is to find some new "good first bug" to work on. This might be a complicated task, as Bug's Ahoy shows only a few not owned good first bugs.
You should try to get in touch with the Fennec team, either via email or IRC (the latter for quicker responses).
Now, to answer your questions, in a more general way
Question 1. Now how do I get some more context on what exactly is the
bug and what is required to be done ?
Usually, this should be described in the first comment in the bug, on Bugzilla. If that's not the case, feel free to drop a message there and ask for more directions. You can also flag the reporter or the mentor of the bug using the needinfo functionality, as they are usually better shown.
As you can see, somebody asked for more info in comment 1 and some new directions were given.
In general, you won't find a patch with code on the bug itself, but you might find links to files and more precise directions on what to change and how. If not, again, feel free to ping the reporter and/or mentor.
Question 2. Am I on the right track on how to figure out the code that
needs to be fixed ?
You're on the right path. In general, if there are no links to files or DXR on the bug, but some code is mentioned, you can look it up using DXR, as you did.
Question 3. Even after reaching the DBUtils.java file I could not find
any documentation about what the class basically does, or where does
it fit into the whole picture. Could someone please help me with this,
as to how do I figure out what a class is supposed to be doing etc. or
at least some documentation around it?
What I usually do when navigating the Firefox code and need some more background on a not so well documented class, is browse the change log for that file, clicking on the Log button in the top-right panel on DXR (when displaying the file). It will show you a list of bugs that affected the file. You can even trace back the original file that implemented it, to get more context.
On the other hand, if you're only interested to the history of a single line of code within a file, then the blame tool is your friend. It tells you who last touched the line, the changeset and the related bug number. That is also accessible from where you can find the Log, here.
In the case of DBUtils.java, however, it looks like the class just holds some utility functions for database access.
To see how something is being used within the Firefox codebase, you can still use DXR. Here's a sample search for the DBUtils object.
I just checked out chromium's source, but I desperately need to learn how to navigate around this monster.
How would I search for parts of the code that implement behavior/features I'm interested in?
Let's say I want to see what happens after a URL is entered into the address bar. How do I find that piece of code?
Or, that I want to see what happens when, while parsing HTML, a certain tag is reached.
I have before me a huge amount of source code, and no skill of navigating around it. How do I learn that skill?
My recommendation for sort of diving in is to take a look at the source for http://code.google.com/p/chromiumembedded/.
It's sort of the condensed version of Chrome and if you look at the files it specifically uses, either ones included in its source tree, or files included therein from the Chromium repo at large. The Chromium code base is a huge amount of stuff, most of which isn't actually in the browser. There's a ton of pulled in code from third party repos which are then boiled down in the build process or Chromium's implementation is located somewhere else in the tree, there's a lot of side projects that (while interesting and an awesome resource for a wide breadth of stuff) will prevent you from achieving your goal of specifically honing in on the browser implementation and how that fits together.
CEF is great because you can see someone who's already done the process of pulling all that stuff together to build a project very specifically scoped at the browser view and nothing else. You can see which parts are primarily derived from webkit easily, you can see where the crossover comes in with Google's implementations, and you can see pretty easily how V8 gets tossed into the mix.
I do say "easily" in relative terms because we're still talking a huge amount of code overall. CEF will put you smack in the center of the requirements, but that stuff is still pulling in the massive amount of various things from the rest of the tree. Compiling it takes me about an hour on a really good computer with 12 gigs of ram and 8 cores, and the generated files take up like 6-10 gigs depending.
At the very least, there's not going to be any sort of quick jump into the shallow end to pick something here or there piecemeal. Browsers are incredibly complex pieces of engineering necessarily, because they have to subsume such a huge amount of individual pieces of functionality and then combine them into a shared context. You may find the one thing you're looking for, but you'll find that it's part of a class library that likely is composed of dozens or hundreds of files, which in turn relies on a hundred more of these libraries to handle each task, so to really take something away you'll have to commit time to taking in a lot more than any given piece of information.
Edit: oh also as your specific example.
src is root http://src.chromium.org/viewvc/chrome/trunk/src
/chrome http://src.chromium.org/viewvc/chrome/trunk/src/chrome
The "chrome" tree largely contains the direct implementations (a lot of stuff isn't in there though, most of it even, but that's the starting point). This has overlap with chromeos (chromeos is kind of chromium browser taken to a crazy extreme)
/chrome/browser http://src.chromium.org/viewvc/chrome/trunk/src/chrome/browser/
Is getting you to close to where you want to be. You start to see specific references to things that you can match to the browser, like the tabs and whatnot (ignoring the giant elephant of the actual browser implementation itself which is what takes up the majority of the mindspace in all this stuff)
/chrome/browser/ui http://src.chromium.org/viewvc/chrome/trunk/src/chrome/browser/ui/
Brings you to where most of the ui code is for the browser. It can be confusing when there's crossover or when stuff migrates, like there's a "ui" in the root src directory which has some crossover.
And finally http://src.chromium.org/viewvc/chrome/trunk/src/chrome/browser/ui/omnibox/
Which has a surprisingly small amount of code in it. But this is what you find a lot. The code here is an implementation of a number of classes that are built up elsewhere. For non-webview gui component you'll find them mostly pointing back to the root "ui" and the native widgets stuff there, which is where the bulk of the actual event handling code is if I remember correctly.
You can try this... it may actually lead somewhere too :-)
http://aaronboodman-com-v1.blogspot.com/2010/10/wherein-i-help-you-get-good-job.html
Reading through the dev forums may help too...
http://groups.google.com/a/chromium.org/group/chromium-dev/topics
Also, this section has a lot of useful documents, such as style guides, etc.
http://dev.chromium.org/developers/contributing-code
Last, but not least, IRC is your friend...
http://dev.chromium.org/developers/irc
I believe, I program good, at least my code produces results...
But I feel I have drawback... I hardly follow any naming conventions... neither for variables.. nor for methods... nor for classes... nor for tables, columns, SPs... Further to this, I hardly comment anything while programming...
I always think that, Let me first see the results and then I will come and correct the var names and other things later... (Thanks to visual studio's reflection here)... But the later does not come...
So, I need tips, to force myself to adopt to the practice of following naming conventions, and commenting...
Edit : I totally understand the ill effects of my practice, and I also know, that it is bad... My question is how do I force myself to follow the discipline...
Are you able to ask others for code reviews? Or even try pair programming? Both of those can really help you to do things you know you really should do.
Also, depending on your language/platform, there may well be lint-like tools you can run to check your code's health.
I hope you get to spend a few years working on code produced by someone else that has the same poor coding practices that you have. Only then will you truly understand how poor your code really is. Code that "works" is the bare minimum, writing code so that it is easy to to support, extend and maintain is where the genius of a good programmer is.
My gut tells me that your code is probably not as good as you think if you have no standards. You really just have to pick something, and stick to it. Being haphazard in coding style probably means you are haphazard in logic, which probably means you have a lot of bugs, and unexpected results in your code that will be hard to deduce later. Good luck.
Just remember the general coding guidelines you need to follow. And as you write the code write as per the guidelines with proper variable naming conventions for variables and methods and have function headers. Dont think whether your code will work or not, and code as per the guidelines.
Comments can be added later, but the naming conventions has to be followed even while doing a proof of concept.
Write your code with a confidence that its going to work.
Have your code reviewed by your peers, and also you can use Fxcop for static code findings.
Best of all, your code should work and should do what it's supposed to. It's what you get paid for.
However, if it is not readable, then it will fade into existence, because in time you will not remember what it does. To avoid this, refactor and document your code as soon as it works. As a rule of thumb, you should not be satisfied with your work before it is documented properly. For each method you write, this should not take too much time. But the longer you wait, the more time it will consume to figure out what your code was supposed to be doing.
I know the best way of all is to document before writing, but that won't work with cowboy coders. The other way around might be a good alternative, because readable and good documented code shows off a developer's skills.
This is a matter of coding discipline. If you want to prototype something and then throw the code away, this is acceptable. However, the instant you need to reuse or debug your code, you will regret having no comments and poor method/variable name choices.
While you are working with the code now, you know what it is doing. In a few months to a year, you will not remember everything so clearly. Then, you will likely regret not commenting your code and not choosing good names.
Consider, too, if someone else were to read your code, how easy would it be to understand?
Running something like StyleCop (if you're writing C#) can go some way towards this. It won't warn you about everything, but you can use it to make sure your methods have documentation comments etc.
However, as others have said coding discipline is something that has to come from within, not without.
If you want to change something about yourself, you need to motivate yourself to change it. That's one of the "rules of life."
This isn't really something Stack Overflow can help you with. I suppose that a good suggestion to build up some motivation is finding yourself a job as a developer and see how far your development habits lead you...
-Carlos Nunez
Whilst working on some generally horrible Javascript code this morning, I came across the following (in multiple places):
// make moveAmount negative
moveAmount = moveAmount - (moveAmount * 2);
I sit directly across from the guy that wrote this; he's been a developer here for seven years. I, on the other hand have just started, am pretty junior and don't claim to know jack.
Nevertheless it has got me wondering about the guy's contortions of simple logic after so many years developing software.
My question is what view others here might take of the overall competancy of a developer that wrote this (3 weeks ago), or does it even reflect at all?
Would anyone point out the convolution?
I, myself, work in constant dread that such judgements be made of me.
Simple solution: Show him the line of code and ask why he did it. It's an opportunity for both of you to learn something. Maybe there was a bug in a browser or some other issue (rounding comes to mind) so the code might break without this. Or he made a mistake. Either way, asking will clear this up.
And while you're right that other people will judge you from the code they see from you, that is not the only thing they take into consideration (and if it is, then you're working at the wrong place -- leave while you're still sane). They will also see when you're polite, curious, helpful.
These things count more than the code you write: Code can be fixed much more easily than angry co-workers.
Your example may be poor code, but I've seen worse (after all, there are circumstances where it will work; some code can't even say that). I think the question you're really asking is: is there any line of code so awful that it means the developer can be deemed incompetent on the basis of that one line?
I say no. I have two children who were terrible sleepers as babies. I've come to work with the flu. I've been at work in death-march mode where I've been working twenty hours in a row. In such circumstances anyone can write a terrible line of code. (This is why such circumstances should be avoided.)
Granted, I would hope I would spot the dreadful code later, and fix it.
Well it works so you would just look like a p**** if you told him that you dislike that code and probably rightly so :) Then again he might have done that code 7 years ago as the very first JavaScript he wrote, but seriously never judge someone from just ONE LINE of code.
Regarding the fear of judgement, relax. It's true, we're all going to be judged by someone at some point, whether it's some pointy-haired boss or maleveolent little upstart. The main thing to get to grips with, I think, is how to get something useful out of every such encounter.
Obviously, there are going to be people griping about things for the sake of it, but you'll also find many similar situations where there's something to be learned.
The suggestion above to start a dialogue with your co-worker is excellent; it may directly feed into just such an encounter, from which either, or both of you, may learn something important.
It's tempting to find one example and generalize about a developer, but unless he has a track record of this sort of nonsense, I would consider it an isolated incident. Simply ask him why he didn't write :
moveAmount = moveAmount * (-1)
this behavior is different from
mountAmount = -moveAmount in the case where 2*moveAmount may cause an overflow if moveAmount was big enough (like 2^32-1 for example).
I don't know if that was his intention though.
Since he wrote it 3 weeks ago, I would say he should be open to criticism for this line. It shows an immaturity that is really inexcusable after 7 years of working professionally.
If he would have at least done this:
moveAmount -= moveAmount * 2;
He would have gotten less flack. It at least shows that he's aware of the other operators and is making some effort to make things more readable.
I don't think that you can always judge people with one line, but the code can tell you so much about a person's aptitude that one line can tell a lot about a person.
I say it will depend on the swallow. If isolated, the line of code you've shown is something I would expect from an exhausted programmer, even if a very competent one. It is an example of something just not very clever and tired people do not so clever things. If, on the other hand that kind of code appears frequently then probably you're working with someone with a twisted mind.
Things that are obvious indications of a bad programmer are related to bad practices. Good programmers will not make huge methods. Even tired, they will try to keep their types loosely coupled. They will avoid exposing public fields instead of exposing them through accessors or properties. They will try inheritance and aggregation as forms of code reuse rather than repeatedly doing copy-paste... The list is long. Those are the kinds of swallows that lead me to almost instantly feel it is summer. :-)
If he wrote that when he was first beginning, he gets a pass. If he wrote that recently, he gets a thumbs down from me. The overall competency of the developer is definitely suspect.
Others are saying you can't judge a developer by one line of code, but I say it can certainly cast doubt upon his competence. I'm not suggesting you jump to conclusions, but that type of code is certainly evidence of a mediocre developer at best.
... and as for it being related to being overtired or stressed or whatever... the bottom line is that code quality is important. If he wrote a one-liner like this, what else may have been written that doesn't stand out so easily?
Caveat: I'm relatively new to coding as well as TextMate, so apologies if there is an obvious answer I'm missing here.
I do a lot of HTML/CSS markup, there are certain patterns that I use a lot, for example, forms, navigation menus etc. What I would like is a way to store those patterns and insert them quickly when I need them.
Is there a way to do this using TextMate?
You can do this very easily in TextMate using Snippets. Just add a new snippet in the bundle editor, and set up how you want to trigger it. You can set a key shortcut, or have it pop up when you hit Tab after a certain word/pattern.
There are many things you can do with them—in your case, it would probably be very useful to set so-called "placeholders" in your snippets, which are the parts that change every time (e.g. the names of the fields in the form). Then, as soon as you insert the snippet, you can hit Tab to move between these.
Along with the links provided above, I think you'll find this screencast useful. It gives a run through of some of the tools TextMate's HTML bundle already provides.
It's probably slightly off-topic though, but worth a look nonetheless.
As mentioned prior snippets are what you are looking for.
For reference look here:
http://manual.macromates.com/en/snippets
http://screenflicker.com/mike/code/div-snippets/