I'm not sure this question should be asked here, but I don't know where else, so I hope it is not banned. And if it is, please address me to a place where it should be asked.
I know in Laravel you can pass a variable called "Bar" to a view like this:
view()->withBar('Foo');
but I don't know how do I know, and the most important, where is it 'officially' explained.
I can find it in the __call function in the code (https://github.com/laravel/framework/blob/5.4/src/Illuminate/View/View.php) but not in the official API.
So, where is it officially explained?
This use to be documented but it has hasn't been included in the docs since 5.0 https://laravel.com/docs/5.0/views#passing-data-to-views.
As with most things with Laravel there are usually a few different ways to do the exact same thing so (for whatever reason) somethings do eventually get omitted from the docs but the functionality doesn't get removed. I would imagine this is because it might be considered a bad practice or not the best approach or even that Taylor may eventually want to remove it...who knows. Either way, there is usually an alternative given to achieve the same outcome.
Hope this helps!
Related
I'd like to know what suggestions there are for Googling (or using other search engines if preferable) for Ruby syntax. I'm very new, and a substantial part of my baptism by fire comes by way of reading other people's code. Ruby in particular can be challenging this way-- it's fantastically compact and easy to read if you know how to read it, so to speak. But figuring that out can be difficult at times. It's worth it, but difficult. So, for example, let's say I encounter an expression like this:
tquery = "#{MASTER_URL}#{query_str}"
Well, apparently there's something going on with the syntax #{stuff}, but what? A variable being manipulated, it seems? If you encountered such an expression and didn't know about interpolation/substitution and have no ready access to someone to ask directly, how would you go about Googling that? That's just an example, of course, but I hope it illustrates the type of problem I'd like to address.
Also, if there are better tags to apply to this post please let me know and I will add. Thank you.
Symbolhound is pretty good for this. For example, here's the search for Ruby's #{}.
Mind, as you can see from the results, it doesn't necessarily come immediately back and tell you what the notation you searched for is named, or how it's defined, but it does return some helpful results to get you started. It's especially useful for punctuation-based syntax elements that are difficult or impossible to search for in other search engines.
Often in code snippets or examples, the prefix My is used for classes, methods, and variables.
We see this all the time, from Google's gcm example to numerous questions on stackoverflow. It can be found in documentation for PHP, Javascript, C#, and really just about every other language.
So, given it's extreme prevalence, why shouldn't I put MyClass with myMethod using myVar1 into production? Why is this bad practice, and what should I do instead?
Name are important
Everything else comes down to that one simple fact.
Having clear, meaningful variable names is an important factor in writing understandable and maintainable code. - Computational Fairy Tales
When you write a piece of code, you want anyone reading it (which includes you in three months!) to know what it does almost immediately. In order to remember, you would probably need to add a comment about it. However...
The proper use of comments is to compensate for our failure to express our self in code - Express Names in Code: Bad vs Clean
To help with this, your name should be both descriptive and concise. Generally, when the prefix My is added, it replaces a prefix that could be more informational. Instead of MyService, why not GcmListenerService?
What if I make it descriptive, but I just add My? Like MyGcmListenerService?
That breaks the consice part of the rule. What do you gain from adding My? Is the My adding value to the name? Even if you were attempting to take possession of the code (which would be better done and is feasible using vcs), My is meaningless. Who wrote My? Well, I did, obviously. It says it right there, "My".
If I really shouldn't use My, why is it in so many examples?
Really, it's just a placeholder.
It's like the metasyntactic variables "foo" and "bar" - it's usually used as a placeholder for a real name. - Opinions on using My as a class name prefix
Unfortunately, most experienced programmers just assume that people looking up examples will know this, and they will replace My with a good variable name when they actually use the code. However, for those new to programming, if you see it all over the place, instead of knowing it is a placeholder, you may think it is actually a standard, and best practice to use My.
Ok, then what do I use instead of My?
There are a lot of really good guides about naming variables and classes out there. You can start with wikipedia, but if you google around a bit you can find lots of articles about good vs bad names. At the heart of it all, though, is one rules: make names descriptive, and keep them concise.
If I read the name of a class, method, or variable and immediately know its purpose, it is a good name.
First of all, in this question I'd like to stay away from the polemic on whether source code commenting is good or bad. I'm just trying to understand more clearly what people mean when they talk about comments that tell you WHY, WHAT or HOW.
We often see guidelines like "Comments should tell you WHY; code itself should tell you HOW". It is easy to agree with the statement on an abstract level. However, people usually drop this like a dogma, and leave the room without further explanation. I've seen this used in so many different places and contexts, that it looks like people can agree on the catchphrase, but they seem to be talking about different things entirely.
So, back to the question: if comments should tell you WHY, what is this WHY we are talking about? Is this the reason why that piece of code exists in the first place? Is this what that piece code should be doing? I would really appreciate if someone could give a clear explanation, and then add some good examples (bad examples are not really needed, but fell free to add them for contrast).
Please do not immediately close this question as duplicate or polemic. I have tried hard to make it very objective. There are many questions on whether comments are good or bad, but no one that addresses the specific question of what are good examples of comments that tell you WHY.
Thanks,
Comments serve two main purposes:
to summarise. Many would say "why document this method when we can just read the code?", but one line of text that describes what a method is for/what it does, can often be much faster to read and easier to understand than 30 lines of code, especially if that code calls other methods that you may need to read as well...
to explain the things that are not obvious from the code - the WHY, or more detail on the how. Simple examples include "we must add the new XmlElement and then remove the old one, as the ReplaceChild method in .net does not work!", or "Uses an iterative Newton-Raphson approach to solve for X ", or "we must not close the port here because the reading thread may still be running", or "use this method where performance is critical, but beware that this method may provide a result that is in error by up to 5%"
(Mathematica version: 8.0.4)
lst = Names["Internal`*"];
Length[lst]
Pick[lst, StringMatchQ[lst, "*Bag*"]]
gives
293
{"Internal`Bag", "Internal`BagLength", "Internal`BagPart", "Internal`StuffBag"}
The Mathematica guidebook for programming By Michael Trott, page 494 says on the Internal context
"But similar to Experimental` context, no guarantee exists that the behavior and syntax of the functions will still be available in later versions of Mathematica"
Also, here is a mention of Bag functions:
Implementing a Quadtree in Mathematica
But since I've seen number of Mathematica experts here suggest Internal`Bag functions and use them themselves, I am assuming it would be sort of safe to use them in actual code? and if so, I have the following question:
Where can I find a more official description of these functions (the API, etc..) like one finds in documenation center? There is nothing now about them now
??Internal`Bag
Internal`Bag
Attributes[Internal`Bag]={Protected}
If I am to start using them, I find it hard to learn about new functions by just looking at some examples and trial and error to see what they do. I wonder if someone here might have a more complete and self contained document on the use of these, describe the API and such more than what is out there already or a link to such place.
The Internal context is exactly what its name says: Meant for internal use by Wolfram developers.
This means, among other things, the following things hold about anything you might find in there:
You most likely won't be able to find any official documentation on it, as it's not meant to be used by the public.
It's not necessarily as robust about invalid arguments. (Crashing the kernel can easily happen on some of them.)
The API may change without notice.
The function may disappear completely without notice.
Now, in practice some of them may be reasonably stable, but I would strongly advise you to steer away from them. Using undocumented APIs can easily leave you in for a lot of pain and a nasty surprise in the future.
Hai guys,
I ve seen people including comments in their program..
Is it to improve inter-programmer communication
and code readability, by explicitly specifying programmers’
intentions and assumptions?
Should comments be in technical terms rather than in natural launguage terms?
How to use comments as effective as possible?
Is it really a good practice adding comments to a program?
Comments should only be used to explain why the code is the way it is. It should never explain what the code is doing. What the code is doing is described by the code.
That being said, some languages have tools that look for special characters in the comments in order to generate documentation. Java is one such language. But these aren't so much code comments as they are documentation that happens to use the same syntax as language comments.
Comments can be used for auto-documentation, communication amongst other developers, memory, todo lists, or basic explanations of functionality. Note that comments ought to be supplementary - if your code needs comments, you need to reconsider your code.
To be as effective as possible, work out a template for your comments to exist in. Again, this will not only help you read and understand your code, but it may help a parser create documentation for you from your comments if they're in a consistent format throughout the code.
Writing clear code is always the first step to making your code easy to understand. You can then explain parts that are not clear by looking at the code, in comments.
For myself, comments explain what I was thinking at the time. That way, six months from now when I don't remember what I was writing, I can use the comments to understand.
Some classic uses of comments:
Explaining why code wasn't done in the most obvious way -- Such as interfacing with systems that use weird or old ways to talk.
Explaining what code might call this code -- Such as in large and complicated system. You can add examples showing code that might need to call this.
Documenting exceptions to current coding practice -- Such as legacy code that hasn't been refactored to use the current systems.
As a rule, if you ever find yourself doing something non-obvious, comment it.
An alternative way of commenting is to start by writing the body of a function as comments. Then break the comments apart and put the code underneath. When it finally works, cleanup and fix the comments.
Ciao!
I try and comment each function describing at a high level, but precise way, what the function does. The precision should be such that it is not necessary to read the body of the function to understand what the function does, or to re-implement it and have it work perfectly with any code that calls it.
Other than that, I try and keep functions small enough that the above is basically all the necessary documentation.
Once in a while, there may be something obscure or odd in what is being done in the code - I document that. Anything that isn't obvious or intuitively right, or that you spent some time thinking about, should be documented.
Just imagine you have a memory problem and will forget writing this program in a month. Then imagine you have to go back and fix it. What would you like commented and how could those comments be made most useful to you?
it's better to make the program self-describing, then no much comments are needed.
First try to write code so people can follow without comments.