> On May 9, 2015, 4:27 a.m., Marco Massenzio wrote: > > include/mesos/executor/executor.hpp, line 22 > > <https://reviews.apache.org/r/33823/diff/1/?file=949197#file949197line22> > > > > please avoid SCREAMING COMMENTS :) > > (also, not sure what is the use of that comment? is it a TODO? should > > we have a #pragma? what?) > > Alexander Rojas wrote: > 1. It is a warning. > 2. The purpose of this header is to be a reflection of > `include/mesos/scheduler/scheduler.hpp`, and so they both have the same > comments, in fact they look mostly identical which follows the maxim of being > consistent. > > Marco Massenzio wrote: > Well, two wrongs don't make one right. > Maybe fix both, or at least let's not perpetuate something that maybe was > not ideal to start with. > > Please change to something that reads like: > > // NOTE: this header only becomes valid after running protoc > // and generating the equivalent .ph.h files > // See: src/messages/mesos.proto > (or whatever the proto file is) > > or something to that effect. > SCREAMING COMMENTS ARE BAD FORM !!!!!! > :-) > > (you could almost hear me screaming, could you? :)))
I think that is the point, when someone is going to fall off a cliff you don't politely ask them to be careful. > On May 9, 2015, 4:27 a.m., Marco Massenzio wrote: > > include/mesos/executor/executor.proto, line 80 > > <https://reviews.apache.org/r/33823/diff/1/?file=949198#file949198line80> > > > > `message` is becoming a truly overloaded term here: as a Protobuf > > message, the Message class, this (string) variable here, the (Message) > > `message` field below... how about `errorMessage` instead? > > Alexander Rojas wrote: > It is called like that, because it is forwarded from the master and to > the master. While I agree with you in principle, you know we like > consistency. Why not discuss it in the HTTP API meeting? > > Marco Massenzio wrote: > I don't understand the "consistency" reference. This is an `error > message` and should be named as such? what is not "consistent" about that? > When we use the same term with (semantically) different meanings, we make > our code more difficult to read and understand - people have to go back and > forth - especially when, as in this case, comments are very few and far > between. The consistency argument goes as follows: It is already widely use in the rest of the code so it is better to continue using it like this. In any case, I brought this issue to the team meeting and I am dropping it as discussed there. > On May 9, 2015, 4:27 a.m., Marco Massenzio wrote: > > include/mesos/executor/executor.proto, line 32 > > <https://reviews.apache.org/r/33823/diff/1/?file=949198#file949198line32> > > > > can we add also a link to the HTTP API design doc? this way for anyone > > looking at the Javadoc, they can follow the link and make some sense of the > > generated classes. > > > > Also, as a general comment, I'd really like all `message`s to have at > > least a brief description, so that the Javadoc that gets generated is > > meaningful to folks writing clients. > > > > As a general rule, we should not expect folks who write against an API > > to have to read the code (they may not even be able to easily access it) > > and, in particular those writing Java are likely to use an IDE that will > > present the javadoc in a pop-up/tooltip upon auto-completion. Added comments. - Alexander ----------------------------------------------------------- This is an automatically generated e-mail. To reply, visit: https://reviews.apache.org/r/33823/#review83125 ----------------------------------------------------------- On May 20, 2015, 8:41 a.m., Alexander Rojas wrote: > > ----------------------------------------------------------- > This is an automatically generated e-mail. To reply, visit: > https://reviews.apache.org/r/33823/ > ----------------------------------------------------------- > > (Updated May 20, 2015, 8:41 a.m.) > > > Review request for mesos, Isabel Jimenez, Marco Massenzio, and Vinod Kone. > > > Repository: mesos > > > Description > ------- > > See summary. > > > Diffs > ----- > > include/mesos/executor/executor.hpp PRE-CREATION > include/mesos/executor/executor.proto PRE-CREATION > src/Makefile.am 34755cf795391c9b8051a5e4acc6caf844984496 > > Diff: https://reviews.apache.org/r/33823/diff/ > > > Testing > ------- > > make check > > > Thanks, > > Alexander Rojas > >
