Most common variables available in surface shaders

P: position of the point being shaded
N: normal (direction) of the point being shaded
E: position of the eye (the camera)
I: incident vector (from E to P)
Cs and Os: color amd opacity of the surface, before shading. These can be given to the renderer by the 3D package (or the RIB).
s and t: texture access coordinates.
L: (only in "illuminance" loops) vector from the light position to P
Cl: (only in "illuminance" loops) color of incoming light

Variables to define in a surface shader

Ci: color of the surface
Oi: opacity of the surface

Most common variables available in light shaders

P: position of the light
Ps: position of the shading point
L: (only in "illuminate" and "solar" loops) vector from P to Ps.

Variable to define in light shaders

Cl: color of the light

Variable names conventions

k: (e.g. ka, kd, ks) Coefficients, usually floats, used to multiply a given component.
n: (e.g. Nn, Ln, Vn) Normalized. Meaning that the lenght of the vector/normal has been set to 1.
f: (e.g. Nf) Faceforward. The vector/normal is facing the camera (thus may have been flipped). See my note on faceforward.
V: -I

Note on opacity

Opacity can be seen as the oposite of transparency, i.e. an opacity of 1 is NOT transparent and vice versa.
When a surface is not fully opaque, you need to scale the color with the intensity (otherwise, there will be "too much color coming from this surface" added to the pixel). This is usually done by Ci *= Oi;

Note on faceforward

Lots of shaders we encounter perform a faceforward of N at the beginning. This is in my opinion because the writers don't know the geometry they shader will be used on. I think that you should be careful with faceforward, and use it only if know that you need it.
This is because it can create artifacts (unwanted flipping of faces on edges of polymeshes), and may be unwanted in some situations (refraction for example, or if you do stereo camera renders). You better make sure that the surfaces of your models are facing outward and restrain the useage of faceforward.

Note on the shading grid (as far as I understand it)

After a REYES renderer has done the spliting and dicing of the geometry for a given bucket, it does the shading. This consists in running all the shading points (within the bucket) through the shaders. But this is not done sequencially for every point. It is done at once for the entire array of points in the grid.
The grid size parameter gives an indication to the renderer of how much memory it should allow for the shading points array (or vector).
Knowing this, we can see how important it is to declare as uniform all the variables we know will be constant for the entire grid. They don't only include user parameters (e.g. number_of_occ_samples), but also other available variable (e.g. rayinfo( "depth" )).
Also, when you print a value (using printf), you can't predict the order of the print statements.

Note on ray tracing and visibility attributes

There are three types of traced rays: transmission rays are for shadows, specular rays are rays shot with a small cone angle (usually for reflections and refractions), and diffuse rays are for large sampling cones (like occlusion and indirectdiffuse).
The threshold of diffuse versus specular cone angle can be set with the Option "trace" "float specularthreshold".
If a ray hits a surface (because the surface is visible for this type of ray), the surface shader may or may not be run. To set the "hitmode", use the Attribute "shade" "string diffusehitmode" (or specularhitmode or transmissionhitmode). If you only need the distance of the hit, the shader doesn't need to be run.
If you do, surface shaders may react differently when triggered by rays. To do that, use rayinfo() to know either the depth, type, label, or other info about the current ray.
Note also that ray 0 is the ray from the camera to the first surface (not really a ray in fact).

Note on ray marching

Interior shaders are traditionally volume shaders that implement ray marching, rendered with Attribute "shade" "string strategy" ["vpvolumes"] (with prman) or Option "render" "integer standardatmosphere" [1] (with 3Delight). You can examine smoke.sl shader for an example of ray marching (Advanced Renderman - Larry Gritz).
But as of prman 15.0, Pixar introduced a new volume rendering technique, where you determine the volume area (volume primitive) with blobbies or with a plugin, and the valume shader deals with Ci and Oi as it would on a surface shader. This should be much simpler than the ray marching technique.