Hacker News Reader

Comment by rcarr | Hacker News Reader

If I remember right, symfony (php framework) has comments that affect how the code runs which as far as I’m concerned means they’re not comments at all but actually code masquerading as comments. Reading about JSDoc gives me the same uneasy feeling, even if it’s not quite the same thing.

Edit:

Here’s one example, you can define your routes in symfony using comments. Not only that, but it’s actually the officially recommended way of doing things. Absolute madness.

https://symfony.com/doc/current/routing.html

View on HN

> as I’m concerned means they’re not comments at all

Smuggling pragmas in comment has a long and rich history. It’s literally the reason why json does not support comments.

> Reading about JSDoc gives me the same uneasy feeling, even if it’s not quite the same thing.

It’s not just “not quite the same thing”, it’s entirely unrelated in every way and shape. JSDoc does not affect the runtime behaviour of its code, or how that code interacts with other systems.

> JSDoc does not affect the runtime behaviour of its code, or how that code interacts with other systems.

At the moment. You’ve literally just said yourself that there is a long history of smuggling code into comments. A few years down the line I don’t want to suddenly have the feature added and then have to be on the look out when I’m debugging a codebase for secret code in comments.

There’s also a long history of smuggling code into JS comments (JSX pragmas, pure), and seemingly noop directives (“use strict”). They’re all hacky but there’s a very strong resistance in the community to mixing intent with JSDoc (good luck signaling anything to TS or eslint in a JSDoc block!). I think it’s safe to write this possibility off as “probably not inevitable”.

I don't see any comments there, I see attributes though [1]. Is that what you meant?

From the page you linked:

> Routes can be configured in YAML, XML, PHP or using attributes. All formats provide the same features and performance, so choose your favorite. Symfony recommends attributes because it's convenient to put the route and controller in the same place.

Attributes are not comments, they are an official structured way of handling metadata.

[1] https://www.php.net/manual/en/language.attributes.overview.p...

I’m sorry, but if it’s using the same starting symbol as a comment, and it’s greyed out in the text editor like a comment, then you can call it whatever you want, but it is a fucking comment. There are a bunch of unused symbol combinations on the keyboard that could have been used, there is absolutely no excuse for it.

> it’s using the same starting symbol as a comment

In Java the keywords "public" and "private" use the same starting symbol too, what's your point? Attributes start with "#[", comments with "//" or "#". That's clear enough.

> it’s greyed out in the text editor like a comment

A language isn't responsible for a specific text editor's syntax highlighting.

> A language isn't responsible for a specific text editor's syntax highlighting.

It’s even greyed out like a comment in the official symfony documentation.

Attributes are a newish thing in Php that got created because people were using comments as code. And yeah, before attributes Symfony would use comments to define routes right above the function definition.

Originally Symfony did use comments (docblock style ones like: /* @Route ... */) for this kind of thing, but since PHP 8 they've moved towards using attributes [1]. The syntax of the attributes #[Route(...)] might look like a comment, but they are actually just valid bits of code you can pragmatically inspect through reflection [2] and then choose to run if you want.

Docblock comments can also be inspected with reflection [3] but have a much looser syntax, so it was up to you to parse them. Where as you can create a new instance of an attribute directly from the reflection object [4]

In your example Symfony uses it to build up the list of HTTP routes by looking through all your controllers for #[Route] attributes. Generally that's done once and then cached, at least in production.

Personally I try to avoid using them, but they're definitely not comments. More like metadata you can attach to classes/methods/properties/parameters then use however you want.

[1]: https://www.php.net/manual/en/language.attributes.syntax.php

[2]: https://www.php.net/manual/en/reflectionclass.getattributes....

[3]: https://www.php.net/manual/en/reflectionclass.getdoccomment....

[4]: https://www.php.net/manual/en/reflectionattribute.newinstanc...

> might look like a comment, but they are actually just valid bits of code

So comments that are code then.

Everyone can sit around going “This is not a pipe it’s a photo of a pipe or my perception of a photo of a pipe”. But if you did not have a sentence above your photo saying “This is not a pipe” or an arts teacher to tell you “this is not a pipe” and there was just a picture of a pipe on the page and someone pointed at it and said “can you tell me what that is?” You would say “why of course, it’s a pipe”. And then all of a sudden it started spouting water out of the end (let’s assume it was a GIF) then you can say “oh it looks like a pipe but it’s actually a water pistol masquerading as a pipe”. The fact that as a dev you have to constantly be on the look out for water pistols masquerading as pipes rather than having a clear distinction between pipes and water pistols is just a piss poor and easily avoidable design decision.

https://en.m.wikipedia.org/wiki/The_Treachery_of_Images

where does it say that JSDoc has runtime implications?

It doesn’t and I say in my comment that it is not the same thing. Nevertheless it gives me the same uneasy feeling because you don’t know what features are going to creep into the language further down the road.

It seems extremley unlikely that Javascript would ever make comments affect the runtime of the language. I'm not sure why there's a fear here why browser vendors/es standards comittees would opt to go down this road?

You’re literally not making any sense.

JSDoc is like 20 years old and not part of the javascript langage, it’s just a way of formatting some comments such that they’re programmatically process able.

JSDoc's PHP equivalent is phpDoc. It's just a way to document things and both are third party libraries that have industry-wide adoption.

What you're thinking of in PHP is not a comment. It's called an Attribute, is built into PHP itself, and while it does use a comment-syntax, it's the old style that is largely unused today ("#" at the start of a line). https://www.php.net/manual/en/language.attributes.overview.p...

JSDoc isn't similar at all, unless you build a compiler that does different things based on your JSDocs.

> has comments that affect how the code runs

> Reading about JSDoc gives me the same uneasy feeling, even if it’s not quite the same thing

The key difference with TypeScript is that even "real" TypeScript types never ever affect runtime behavior, they are purely descriptive. This is an explicit goal of the project (and they've had to make some compromises in other areas to uphold it), so I don't see it ever changing

That’s a PHP attribute:

https://php.watch/articles/php-attributes

Are they not using attributes, which start with a #? I thought PHP had C style // comments.

They are attributes. PHP does also allow # as a comment character in addition to // style comments and I assume that's where the poster got confused.

You can call it an “attribute” and you can also call it a “comment that affects the code” - they’re both just labels for the same thing. If you don’t want the latter to be a legitimate label (and it is, because I’ve communicated that idea with those words and you’ve understood what I’m referring to immediately) then the solution is to use any other symbol other than those reserved for comments. Imagine if we just had something like const a = 2 * 3 *[pineapples] * 10 and pineapples was coloured in like a variable in your syntax highlighting and people were like oh yeah don’t worry about that, that’s just a comment in the middle of the arithmetic. It’s ludicrous.

Is this all because it uses the hash symbol? I mean, you could probably call anything a "comment that affects code" if we want to get abstract. Attributes are in a bunch of languages, but they aren't comments. Comparing them to comments just feels like you're ignoring the fact that they are code that affects runtime.

Reply on news.ycombinator.com