Can somebody explain what the Jekyll's life cycle is ? I mean in what order the variables are created/collected, the urls are constructed, the pages/posts are rendered.
I hope that this will help me to understand for example why some variables can be overwritten and other can't (for example I can't set a permalink: pretty in the front metter of a page), why we can't set more than one layout, and so on ...
Probably the best way to understand this is to read the code, but I'm not a Ruby programmer :(
Related
Some of the pleasure of writing in markdown is the ability to spread links all over the place (I wish [[link]] worked though). Odds are that I've made a typo or just plain forgot to actually fill in some of the links.
Is there a way to easily write a regression test inside jekyll that will follow all the (internal) links and tell me if I've missed something?
There probably is... but the easiest way to test this would be to run your website through something like this: https://www.deadlinkchecker.com/website-dead-link-checker.asp
I started using core-style in (mostly) all of my components. On 0.4 it was pretty helpful, but i can't really see why should i use it now with 0.5. Is there any specifics to when should i use it?
Any case in particular?
ps.: The thing is: data-binding had a bunch of problems which i haven't encountered so far on .5. Can anyone help me? I know it's a bit broad question but i don't want to go through the trouble of getting it out of my code then back in again just so i know where i should actually be using it.
Core-style is useful to create shared themes across the application. Take a look at this artcile http://pascalprecht.github.io/2014/08/01/sharing-styles-across-web-components-with-polymer-and-core-style/
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
[This question is somewhat related to this question, but the answers are not...]
I have always used relative paths in HTML and scripting languages (PHP/ASP/JSP) to refer to EVERYTHING. I think the justification had to do with 'what if the website gets hosted in some weird subdirectory.' But my coworker has started throwing absolute paths into a PHP site we're working on. At first I was appalled, but then I thought, "why not? We'll never be hosted in a subdirectory." Nowadays, getting hosted in the root is not an uncommon necessity. Is it still necessary to "code" (markup, really) with relative paths? I think it's probably an antiquated practice by now.
Definitely. You never know where your code is going to end up, or for what purpose.
Suppose you build a new version of a site, but to help your users transition, you move the old version to a "/classic" subdirectory. The same often happens the other way around where sites will host a beta version of the new redesign in a "/new" directory.
Building it properly the first time shouldn't be a hassle, and you'll thank yourself for it one day.
Well, it's probably not the end of the world but it's building in a dependency that you don't need.
If for example you ever want to put a number of versions in subdirectories in a test harness, or subdirectories help to work around some other issue (such as combining this with some other app that insists on being in the root), you may find it harder.
Sure, you can probably always work around it in some other way - but the problem is you now have to.
Edit: Killed my opening paragraph as it was based on a miss-interpretation of the referenced article.
I always use an absolute path for the following reasons:
Includes:
1. When you use a templating system, you never know the directory structure that a document is going to have when it's calling the include.
2. If documents are going to be moved around, you can be pretty sure it's going to be the documents themselves rather than the includes. If it is the includes, then they're being moved my someone who knows what going on. Added to this, if it is someone not familiar with absolute/relative path, they'll understand absolute a lot better than relative.
css: (as well as the items above)
1. When editing with Web Developer, relative backgrounds disappear when your style sheet isn't in the same directory as the doc.
2. By spec, when you put something on the 'Net, it should be there for the duration. When I'm building something new, I build it in a new folder, or with a new file name and leave all the old docs alone.
If you're using dynamically-generated pages, dynamically generate your URLs. For example, with JSTL use <c:url>. Not only does this allow you to move your pages in the future, it also ensures that your URLs will be properly escaped (tell the truth: how often do you build query strings with &? if you want the W3C validator to accept them, you need to).
For my personal website, which uses PHP to build pages, I've created several methods: insertPageRef(), insertCodeRef(), and so on, that create valid HREFs. As a result, I don't hesitate to re-arrange my site structure as it evolves.
The case of being moved to a subdirectory is fairly unusual, I'd say. Far more usual is being hosted on different servers: you create your site for testing on "dev.yourcompany.com" then go live by moving it to "www.yourcompany.com". In that case, you need to use relative links for obvious reasons.
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.